|
1 | | - |
2 | | -# Cloudinary React Library |
3 | | - |
4 | | -Cloudinary is a cloud service that offers a solution to a web application's entire image management pipeline. |
5 | | - |
6 | | -Easily upload images to the cloud. Automatically perform smart image resizing, cropping and conversion without installing any complex software. Integrate Facebook or Twitter profile image extraction in a snap, in any dimension and style to match your website’s graphics requirements. Images are seamlessly delivered through a fast CDN, and much much more. |
7 | | - |
8 | | -Cloudinary offers comprehensive APIs and administration capabilities and is easy to integrate with any web application, existing or new. |
9 | | - |
10 | | -Cloudinary provides URL and HTTP based APIs that can be easily integrated with any Web development framework. |
| 1 | +Cloudinary React SDK |
| 2 | +========================= |
| 3 | +## About |
| 4 | +The Cloudinary React SDK allows you to quickly and easily integrate your application with Cloudinary. |
| 5 | +Effortlessly optimize and transform your cloud's assets. |
| 6 | + |
| 7 | +#### Note |
| 8 | +This Readme provides basic installation and usage information. |
| 9 | +For the complete documentation, see the [React SDK Guide](https://cloudinary.com/documentation/react1_integration). |
| 10 | + |
| 11 | + |
| 12 | +## Table of Contents |
| 13 | +- [Key Features](#key-features) |
| 14 | +- [Version Support](#Version-Support) |
| 15 | +- [Installation](#installation) |
| 16 | +- [Usage](#usage) |
| 17 | + - [Setup](#Setup) |
| 18 | + - [Transform and Optimize Assets](#Transform-and-Optimize-Assets) |
| 19 | + - [Generate Image and HTML Tags](#Generate-Image-and-Video-HTML-Tags) |
| 20 | + |
| 21 | +## Key Features |
| 22 | +- [Transform](https://cloudinary.com/documentation/react1_video_manipulation#video_transformation_examples) and [optimize](https://cloudinary.com/documentation/react1_image_manipulation#image_optimizations) assets. |
| 23 | +- Generate [image](https://cloudinary.com/documentation/react1_image_manipulation#deliver_and_transform_images) and [video](https://cloudinary.com/documentation/react1_video_manipulation#video_element) tags. |
| 24 | + |
| 25 | +## Version Support |
| 26 | +| SDK Version | React 15.3 | React 16.2 | React 16.3 | React 17 | |
| 27 | +|---------------|------------|------------|------------|----------| |
| 28 | +| 1.6.8 & up | X | X | V | V | |
| 29 | +| 1.2.0 - 1.6.7 | X | X | V | X | |
| 30 | +| 1.0.5 - 1.1.4 | X | V | X | X | |
| 31 | +| 1.0.0 - 1.0.4 | V | X | X | X | |
11 | 32 |
|
12 | 33 | ## Installation |
13 | | - |
14 | | - |
15 | | -### NPM |
16 | | - |
17 | | -1. Install the files using the following command. Use the optional `--save` parameter if you wish to save the dependency in your `bower.json` file. |
18 | | - |
19 | | - ```shell |
20 | | - npm install cloudinary-react --save |
21 | | - ``` |
22 | | - |
23 | | -1. Include the javascript files in your code. For Example: |
24 | | - |
25 | | - ```js |
26 | | - import {Image} from 'cloudinary-react'; |
27 | | - ``` |
28 | | - |
29 | | - |
30 | | -## Setup |
31 | | - |
32 | | -In order to properly use this library you have to provide it with a few configuration parameters. All configuration parameters can be applied directly to the element or using a CloudinaryContext element. |
33 | | - |
34 | | - |
35 | | -```js |
36 | | -ReactDOM.render( |
37 | | - <div> |
38 | | - <h1>Hello, world!</h1> |
39 | | - <Image cloudName="demo" publicId="sample" width="300" crop="scale"/> |
40 | | - // Or for more advanced usage: |
41 | | - // import {CloudinaryContext, Transformation} from 'cloudinary-react'; |
42 | | - <CloudinaryContext cloudName="demo"> |
43 | | - <Image publicId="sample"> |
44 | | - <Transformation width="200" crop="scale" angle="10"/> |
45 | | - </Image> |
46 | | - </CloudinaryContext> |
47 | | - </div>, |
48 | | - document.getElementById('example') |
49 | | - ); |
| 34 | +### Install using your favorite package manager (yarn, npm) |
| 35 | +```bash |
| 36 | +npm install cloudinary-react |
| 37 | +``` |
| 38 | +Or |
| 39 | +```bash |
| 40 | +yarn add cloudinary-react |
50 | 41 | ``` |
51 | | - |
52 | | -Required: |
53 | | - |
54 | | -* `cloudName` - The cloudinary cloud name associated with your Cloudinary account. |
55 | | - |
56 | | -Optional: |
57 | | - |
58 | | -* `privateCdn`, `secureDistribution`, `cname`, `cdnSubdomain` - Please refer to [Cloudinary Documentation](https://cloudinary.com/documentation/react_integration#3_set_cloudinary_configuration_parameters) for information on these parameters. |
59 | | - |
60 | 42 |
|
61 | 43 | ## Usage |
62 | | - |
63 | | -The library includes 6 Components: |
64 | | - |
65 | | -* CloudinaryContext |
66 | | -* Image |
67 | | -* Audio |
68 | | -* Video |
69 | | -* Transformation |
70 | | -* Placeholder - can only be used as child of an Image component |
71 | | - |
72 | | -## Components Demo |
73 | | -Storybook for the components is available [here](https://cloudinary.github.io/cloudinary-react/) |
74 | | - |
75 | | -### CloudinaryContext |
76 | | -CloudinaryContext allows you to define shared parameters that are applied to all children elements. |
77 | | - |
78 | | -### Image |
79 | | -The Image element defines a Cloudinary Image tag. |
80 | | - |
81 | | -### Video |
82 | | -The Video element defines a Cloudinary Video tag. |
83 | | - |
84 | | -### Transformation |
85 | | -The Transformation element allows you to defined additional transformations on the parent element. |
86 | | - |
87 | | -For example: |
88 | | - |
89 | | -``` |
90 | | -<Image cloudName="demo" publicId="sample"> |
91 | | - <Transformation angle="-45"/> |
92 | | - <Transformation effect="trim" angle="45" crop="scale" width="600"> |
93 | | - <Transformation overlay="text:Arial_100:Hello" /> |
94 | | - </Transformation> |
95 | | -</Image> |
| 44 | +### Setup |
| 45 | +```javascript |
| 46 | +import React from 'react'; |
| 47 | +import {Image, Video, Transformation} from 'cloudinary-react'; |
96 | 48 | ``` |
97 | 49 |
|
98 | | - |
99 | | -The Cloudinary Documentation can be found at: |
100 | | -https://cloudinary.com/documentation/react_integration |
101 | | - |
102 | | -## Additional resources |
103 | | - |
104 | | -Additional resources are available at: |
105 | | - |
106 | | -* [Website](http://cloudinary.com) |
107 | | -* [Documentation](http://cloudinary.com/documentation) |
108 | | -* [Knowledge Base](http://support.cloudinary.com/forums) |
109 | | -* [Image transformations documentation](http://cloudinary.com/documentation/image_transformations) |
110 | | - |
111 | | -## Support |
112 | | - |
113 | | -You can [open an issue through GitHub](https://github.com/cloudinary/cloudinary_js/issues). |
114 | | - |
115 | | -Contact us at [http://cloudinary.com/contact](http://cloudinary.com/contact). |
116 | | - |
117 | | -Stay tuned for updates, tips and tutorials: [Blog](http://cloudinary.com/blog), [Twitter](https://twitter.com/cloudinary), [Facebook](http://www.facebook.com/Cloudinary). |
118 | | - |
119 | | -## Join the Community ########################################################## |
120 | | - |
121 | | -Impact the product, hear updates, test drive new features and more! Join [here](https://www.facebook.com/groups/CloudinaryCommunity). |
122 | | - |
123 | | -## Updating github pages |
124 | | -The github pages source is the "gh-pages" branch. To generate updated storybook: |
125 | | -1. Switch to "gh-pages" branch |
126 | | -2. pull from master |
127 | | -3. rebuild storybook by running "npm run build-storybook" |
128 | | -4. commit and push |
129 | | - |
130 | | -## License |
131 | | - |
| 50 | +### Transform and Optimize Assets |
| 51 | +- [See full documentation](https://cloudinary.com/documentation/react1_image_manipulation) |
| 52 | + |
| 53 | + ```jsx |
| 54 | + // Apply a single transformation |
| 55 | + <Image cloudName="demo" publicId="sample"> |
| 56 | + <Transformation crop="scale" width="200" angle="10" /> |
| 57 | + </Image> |
| 58 | + ``` |
| 59 | + |
| 60 | + ```jsx |
| 61 | + // Chain (compose) multiple transformations |
| 62 | + <Image cloudName="demo" publicId="sample"> |
| 63 | + <Transformation angle="-45" /> |
| 64 | + <Transformation effect="trim" angle="45" crop="scale" width="600" /> |
| 65 | + <Transformation overlay="text:Arial_100:Hello" /> |
| 66 | + </Image> |
| 67 | + ``` |
| 68 | +### Generate Image and Video HTML Tags |
| 69 | + - Use <Image> to generate image tags |
| 70 | + - Use <Video> to generate video tags |
| 71 | + |
| 72 | +### File upload |
| 73 | +This SDK does not provide file upload functionality, however there are [several methods of uploading from the client side](https://cloudinary.com/documentation/react1_image_and_video_upload). |
| 74 | + |
| 75 | +## Contributions |
| 76 | +- Ensure tests run locally (```npm run test```) |
| 77 | +- Open a PR and ensure Travis tests pass |
| 78 | + |
| 79 | +## Get Help |
| 80 | +If you run into an issue or have a question, you can either: |
| 81 | +- [Open a Github issue](https://github.com/CloudinaryLtd/cloudinary-react/issues) (for issues related to the SDK) |
| 82 | +- [Open a support ticket](https://cloudinary.com/contact) (for issues related to your account) |
| 83 | + |
| 84 | +## About Cloudinary |
| 85 | +Cloudinary is a powerful media API for websites and mobile apps alike, Cloudinary enables developers to efficiently manage, transform, optimize, and deliver images and videos through multiple CDNs. Ultimately, viewers enjoy responsive and personalized visual-media experiences—irrespective of the viewing device. |
| 86 | + |
| 87 | + |
| 88 | +## Additional Resources |
| 89 | +- [Cloudinary Transformation and REST API References](https://cloudinary.com/documentation/cloudinary_references): Comprehensive references, including syntax and examples for all SDKs. |
| 90 | +- [MediaJams.dev](https://mediajams.dev/): Bite-size use-case tutorials written by and for Cloudinary Developers |
| 91 | +- [DevJams](https://www.youtube.com/playlist?list=PL8dVGjLA2oMr09amgERARsZyrOz_sPvqw): Cloudinary developer podcasts on YouTube. |
| 92 | +- [Cloudinary Academy](https://training.cloudinary.com/): Free self-paced courses, instructor-led virtual courses, and on-site courses. |
| 93 | +- [Code Explorers and Feature Demos](https://cloudinary.com/documentation/code_explorers_demos_index): A one-stop shop for all code explorers, Postman collections, and feature demos found in the docs. |
| 94 | +- [Cloudinary Roadmap](https://cloudinary.com/roadmap): Your chance to follow, vote, or suggest what Cloudinary should develop next. |
| 95 | +- [Cloudinary Facebook Community](https://www.facebook.com/groups/CloudinaryCommunity): Learn from and offer help to other Cloudinary developers. |
| 96 | +- [Cloudinary Account Registration](https://cloudinary.com/users/register/free): Free Cloudinary account registration. |
| 97 | +- [Cloudinary Website](https://cloudinary.com): Learn about Cloudinary's products, partners, customers, pricing, and more. |
| 98 | + |
| 99 | + |
| 100 | +## Licence |
132 | 101 | Released under the MIT license. |
0 commit comments