# Set up the Cloudinary plugin

The Builder Cloudinary plugin provides an easy-to-use component block with access to your Cloudinary images.

Follow the steps below to enable Cloudinary in your Builder Space.

## Create an API Key in Cloudinary

To create an API key in Cloudinary:

1. Go to your Cloudinary dashboard.
2. Go to **Settings**.
3. Click **API Keys**.
4. Click **\+ Generate New API Key**.
5. A confirmation code is sent to the account email. Use this confirmation code to approve the new API key.
6. Optionally, rename the API key from **Untitled** to something more descriptive, like **Builder API Key**.

## Enable the plugin in Builder

To enable the Cloudinary plugin in Builder:

1. Go to [Plugins](/content/app/integrations/index.html) in Builder.
2. Find the Cloudinary tile, either by scrolling or using the search bar.
3. Toggle on the Cloudinary plugin.

## Create a custom component

Next, you'll need to create a custom component. This component is the block that can be added to individual content entries within Builder.

Below is an example of a Cloudinary component using the React Gen 2 SDK.

```javascript
import { RegisteredComponent } from "@builder.io/sdk-react";

const CustomCloudinaryComponent = ({ cloudinaryOptions }: any) => {
    const url = cloudinaryOptions?.url;
    const alt = cloudinaryOptions?.context?.custom?.alt || "Cloudinary Asset";
    const component = url ? (
        <img src={url} alt={alt} />
    ) : (
        <img src="https://placehold.co/600x400?text=Cloudinary+Asset+Placeholder" alt="Cloudinary placeholder" />
    );
    return component;
};

export const cloudinaryImageConfig: RegisteredComponent = {
    component: CustomCloudinaryComponent,
    name: "Cloudinary Assets",
    inputs: [{ name: "cloudinaryOptions", type: "cloudinaryImageEditor" }],
};
```

The code above does the following:

- Imports `RegisteredComponent` from the appropriate Builder SDK.
- Creates a custom component called `CustomCloudinaryComponent`. This component displays the selected Cloudinary image, or a placeholder image if none has been selected.
- Creates a registered component configuration object.

Make sure to register your component, as is appropriate for your framework and Builder SDK generation. For more details, visit [Register custom components](/content/c/docs/custom-components-setup/index.html).

For the React Gen 2 SDK, include your custom components as an attribute on the returned component of your content entry.

```javascript
return (
    <Content content={content} model="page" apiKey={BUILDER_API_KEY} customComponents={[cloudinaryImageConfig]} />
);
```

## Configure and use your component

Once your component is registered, go to a content entry within your Builder Space and do the following:

1. Under the **Insert** menu, go to **Custom Components** and drag your Cloudinary Block to your content entry.
2. Click **Set Credentials**.
3. Add your **API key** and **Cloud name**. This configuration step only needs to happen one time.
4. Click the **Choose Image** button.
5. Select your image from Cloudinary.

## Image payload example

Below is an example of the payload delivered by Cloudinary to your custom component. All data is stored within the key `cloudinaryOptions`.

```json
{
    "public_id": "sample",
    "resource_type": "image",
    "type": "upload",
    "format": "jpg",
    "version": 1511474034,
    "url": "http://res.cloudinary.com/demo/image/upload/v1511474034/sample.jpg",
    "secure_url": "https://res.cloudinary.com/demo/image/upload/v1511474034/sample.jpg",
    "width": 864,
    "height": 576,
    "bytes": 120257,
    "duration": null,
    "tags": [],
    "metadata": [],
    "created_at": "2023-02-08T08:38:51Z",
    "derived": [
        {
            "url": "http://res.cloudinary.com/demo/image/upload/c_scale,e_grayscale,f_auto,q_auto,w_100/v1511474034/sample.jpg",
            "secure_url": "https://res.cloudinary.com/demo/image/upload/c_scale,e_grayscale,f_auto,q_auto,w_100/v1511474034/sample.jpg"
        }
    ],
    "access_mode": "public",
    "access_control": [],
    "created_by": {
        "type": "user",
        "id": "abc123def456ghiabc123def456ghi"
    },
    "uploaded_by": {
        "type": "user",
        "id": "xyz789efg456qrsxyz789efg456qrs"
    },
    "id": "ede59e6d3befdc65a8adc2f381c0f96f",
    "folder_id": "abcs432p8xyz0q532wqpoirnk0138",
    "context": {
        "custom": {
            "alt": "Text that describes the image",
            "caption": "Caption or title that is presented along with the image"
        }
    }
}
```

## What's next

For more details on custom components, visit [Register custom components](/content/c/docs/custom-components-setup/index.html). For more details on plugins, visit [Intro to plugins](/content/c/docs/plugins-intro/index.html).