> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# jQuery SDK


[changelog-link]: https://github.com/cloudinary/pkg-cloudinary-jquery/releases

The Cloudinary jQuery SDK provides simple, yet comprehensive image and video upload, rendering, transformation, optimization, and delivery capabilities that you can implement using code that integrates seamlessly with your existing jQuery application.

## How would you like to learn?

{table:class=no-borders overview}Resource | Description 
--|--
[Sample projects](#sample_projects) | Explore sample projects to see how to implement jQuery functionality such as rendering and delivery with transformations.
[Cloudinary jQuery SDK GitHub repo](https://github.com/cloudinary/pkg-cloudinary-jquery) | Explore the source code and see the [Releases][changelog-link] for details on all new features and fixes from previous versions. 
[Video tutorials](tutorial_screencasts) | Watch tutorials relevant to your use cases to learn how to use Cloudinary features. 

Other helpful resources...

This guide focuses on how to set up and implement popular Cloudinary capabilities using the jQuery SDK, but it doesn't cover every feature or option. Check out these other resources to learn about additional concepts and functionality in general. 

{table:class=no-borders overview}Resource | Description 
--|--
[Developer kickstart](dev_kickstart) |A hands-on, step-by-step introduction to Cloudinary features.
[Glossary](cloudinary_glossary) | A helpful resource to understand Cloudinary-specific terminology.
[Guides](programmable_media_guides) | In depth guides to help you understand the many, varied capabilities provided by the product. 
[References](cloudinary_references) | Comprehensive references for all APIs, including jQuery code examples.

> **NOTE**: This page describes Cloudinary's jQuery frontend library. For the backend Node.js library, see the [Node.js documentation](node_integration).

## Install

Install the jQuery library using a package manager: 

```
# For NPM:   
npm install jquery
npm install cloudinary-jquery-file-upload

# For Bower: 
bower install cloudinary-jquery --save
```

The optional `--save` parameter saves the dependency in your `bower.json` file.

## Configure

### Include jQuery 

Include the files in your HTML page:

```html
// always required
<script src="[folder-path]/jquery/dist/jquery.js" type="text/javascript"></script>

// the following files only need to be included if you want to implement client-side uploading
<script src="[folder-path]/blueimp-file-upload/js/vendor/jquery.ui.widget.js" type="text/javascript"></script>
<script src="[folder-path]/blueimp-file-upload/js/jquery.iframe-transport.js" type="text/javascript"></script>
<script src="[folder-path]/blueimp-file-upload/js/jquery.fileupload.js" type="text/javascript"></script>
<script src="[folder-path]/cloudinary-jquery-file-upload/cloudinary-jquery-file-upload.js" type="text/javascript"></script>
// [folder-path] is the mapping to the resources in your web application
```  

### Set required configuration parameters

To use the Cloudinary jQuery library you have to configure at least your `cloud_name`. 

An instance of the Cloudinary jQuery main class, `CloudinaryJQuery`, is already instantiated as `$.cloudinary`. 

You can set configuration parameters either programmatically in each call to a Cloudinary method or globally using the Cloudinary `config` method, for example:

```js
$.cloudinary.config({ cloud_name: 'my_cloud'});
```

> **NOTES**:
>
> * Most functionality implemented on the client side doesn't require authentication, so only your `cloud_name` is _required_ to be configured, and not your API key or secret. Your API secret should never be exposed on the client side, so if you want to use [signed uploads](upload_images#authenticated_requests) or [generate delivery signatures](delivery_url_signatures), you'll also need server-side code, for which you can use one of our [backend SDKs](cloudinary_sdks#cloudinary_sdks).* For backward compatibility reasons, the default value of the optional `secure` configuration parameter is `false`. However, for most modern applications, it's recommended to configure the `secure` parameter to `true` to ensure that your transformation URLs are always generated as HTTPS.

### Set additional configuration parameters

In addition to the required configuration parameters, you can define a number of optional [configuration parameters](cloudinary_sdks#configuration_parameters) if relevant. 

For example, to ensure that your transformation URLs are always generated as HTTPS, in addition to configuring the `cloud_name`, you can set the `secure` configuration parameter to `true`:

```js
$.cloudinary.config({ cloud_name: 'my_cloud', secure: true});
```

## Use

Once you've installed and configured the jQuery SDK, you can use it for:

* **Uploading files to your product environment** - Direct unsigned file upload from the browser. [See example](#quick_example_file_upload)
* **Transforming images** - Build URLs and render your images with transformations applied. [See example](#quick_example_image_transformations)
* **Transforming videos** - Build URLs and render your videos with transformations applied. [See example](#quick_example_video_transformations)

### Quick example: File upload

The following code demonstrates defining a file `input` field for client-side image or video file upload, and then initializing the input field for use with the `cloudinary_fileupload` method:

```html
<input name="file" type="file" class="cloudinary-fileupload" data-cloudinary-field="image_id" 
   data-form-data="[upload-preset-and-other-upload-options-as-html-escaped-JSON-data]"></input>
```

```js
$(document).ready(function() {
    $("input.cloudinary-fileupload[type=file]").cloudinary_fileupload();
});
```

> **Learn more about file upload**:
>
> * See more information about [jQuery image and video upload](jquery_image_and_video_upload).

### Quick example: Image transformations

Take a look at the following transformation code and the image it delivers:

![sample transformation](https://res.cloudinary.com/demo/image/upload/c_thumb,g_face,h_150,w_150/r_20/e_sepia/l_cloudinary_icon/e_brightness:90/o_60/c_scale,w_50/fl_layer_apply,g_south_east,x_5,y_5/a_10/front_face.png "secure: true, disable_all_tab: true, with_url: false, frameworks:jquery")

```jquery
$.cloudinary.image("front_face.png", {transformation: [
  {gravity: "face", height: 150, width: 150, crop: "thumb"},
  {radius: 20},
  {effect: "sepia"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon")},
  {effect: "brightness:90"},
  {opacity: 60},
  {width: 50, crop: "scale"},
  {flags: "layer_apply", gravity: "south_east", x: 5, y: 5},
  {angle: 10}
  ]})
```

This relatively simple code performs all of the following on the original front_face.jpg image before delivering it:

* **Crop** to a 150x150 thumbnail using face-detection gravity to automatically determine the location for the crop
* **Round the corners** with a 20 pixel radius
* Apply a **sepia effect**
* **Overlay the Cloudinary logo** on the southeast corner of the image (with a slight offset). The logo is scaled down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%)
* **Rotate** the resulting image (including the overlay) by 10 degrees
* **Convert** and deliver the image in PNG format (the originally uploaded image was a JPG)

And here's the URL that's automatically generated from the above code:

![sample transformation](https://res.cloudinary.com/demo/image/upload/c_thumb,g_face,h_150,w_150/r_20/e_sepia/l_cloudinary_icon/e_brightness:90/o_60/c_scale,w_50/fl_layer_apply,g_south_east,x_5,y_5/a_10/front_face.png "secure: true, disable_all_tab: true, with_code:false, with_image:false")

> **Learn more about image transformations**:
>
> * Read the [image transformation guide](image_transformations) to learn about the different ways to transform your images.

> * See more examples of [image transformations](jquery_image_manipulation) using the Cloudinary jQuery SDK.   

> * See all possible transformations in the [Transformation URL API reference](transformation_reference).

### Quick examples: Video transformations

Here are two quick examples to get you started with video transformations:

* [Video transformation example 1](#video_transformation_example_1) - Adjust the brightness of a video
* [Video transformation example 2](#video_transformation_example_2) - Apply multiple transformations as chained transformations

#### Video transformation example 1

The following jQuery code renders the ship.mp4 video with a brightness adjustment applied:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/e_brightness:20/ship.mp4 "thumb: c_scale,w_300, disable_all_tab: true, with_url: false, frameworks:jquery")

```jquery
$.cloudinary.video("ship", {effect: "brightness:20"})
```

This code renders the following transformation URL:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/e_brightness:20/ship.mp4 "with_url:true, with_code:false, thumb: c_scale,w_300")

#### Video transformation example 2

You can apply more than one transformation at a time (see [chained transformations](video_manipulation_and_delivery#chained_transformations)) to give more interesting results:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/ar_1:1,c_fill,g_auto,w_300/e_blur:50/r_max/ship.mp4 "disable_all_tab: true, with_url: false, frameworks:jquery")

```jquery
$.cloudinary.video("ship", {transformation: [
  {aspect_ratio: "1:1", gravity: "auto", width: 300, crop: "fill"},
  {effect: "blur:50"},
  {radius: "max"}
  ]})
```

This relatively simple code performs all of the following on the original ship.mp4 video before delivering it:

* **Crop** to a 1:1 aspect ratio (square) with a width of 300 pixels, using automatic gravity to determine the focal point
* Apply a **blur effect** with strength 50
* Apply **maximum rounding** to create a circular video

And here's the URL that's automatically generated and rendered from the above code:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/ar_1:1,c_fill,g_auto,w_300/e_blur:50/r_max/ship.mp4 "disable_all_tab: true, with_code:false, with_image:false")

> **Learn more about video transformations**:
>
> * Read the [video transformation guide](video_manipulation_and_delivery) to learn about the different ways to transform your videos.

> * See more examples of [video transformations](jquery_video_manipulation) using the Cloudinary jQuery SDK.  

> * See all possible transformations in the [Transformation URL API reference](transformation_reference).

> * See all JavaScript transformation actions and qualifiers in the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/list_namespace.html).
## Sample projects

The following sample project demonstrates a dynamic HTML page using Cloudinary's jQuery plugin (within a Ruby backend project) to perform direct uploading from the browser, including uploading progress, and an image preview with advanced transformations:

[Photo Album sample project](https://github.com/cloudinary/cloudinary_gem/blob/master/samples/photo_album/app/views/photos/new_direct.html.erb)

> **READING**:
>
> * See examples of powerful [image](jquery_image_manipulation) and [video](jquery_video_manipulation) transformations using jQuery code, and see our [image transformation](image_transformations) and [video transformation](video_manipulation_and_delivery) docs.   

> * For information about uploading images and videos from a jQuery application, see [jQuery image and video upload](jquery_image_and_video_upload).

> * Stay tuned for updates by following the [Release Notes](programmable_media_release_notes) and the [Cloudinary Blog](https://cloudinary.com/blog).