Getting Started with CldUploadWidget

The CldUploadWidget creates a new instance of the Cloudinary Upload Widget giving you an easy way to add upload capabilities to your Astro project.

Basic Usage

The CldUploadWidget will not render any UI by default. It will instead only render what’s passed through in a <slot />.

By default, the widget looks for any <button> nested in the Slot, where upon clicking that button, the widget is opened.

Throughout the upload lifecycle, including selecting an asset, uploading an asset, and more, events are triggered on the component instance, allowing you to listen for those events and update the UI or data store with the results.

Uploading to Cloudinary

There are two options when using the CldUploadWidget: signed and unsigned. These options allow you to control the amount of security and restrictions you place on uploads.

Tip

To learn more about signed and unsigned upload, check out the Cloudinary docs.

Unsigned

To give unsigned access for upload, provide an upload preset as part of the component configuration.

Caution

The upload preset for unsigned uploads requires that unsigned uploads are permitted.

Use the following to generate an unsigned upload widget:

Upload

Note

All files uploaded to this demo will be deleted.

---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget uploadPreset="<Your Upload Preset>">
  <button>Upload</button>
</CldUploadWidget>

Signed

Signing upload requests requires passing in an endpoint to the component.

You can do this by creating a serverless function that reads the parameters as the body and returns an object with the signature.

Use the following to generate an signed upload widget:

Upload

Note

All files uploaded to this demo will be deleted.

---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget signatureEndpoint="<API Endpoint (ex: /api/sign-cloudinary-params)>">
  <button>Upload</button>
</CldUploadWidget>

Here’s an example of how you could process the signature in an API endpoint that signs a request:

import type { APIRoute } from "astro";
import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
});

export const prerender = false;

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  const { paramsToSign } = body;
  const signature = cloudinary.utils.api_sign_request(paramsToSign, import.meta.env.CLOUDINARY_API_SECRET);
  return Response.json({ signature });
}

• Expand Snippet
• Collapse Snippet

To use the above, create a Node-based API route, add the snippet, and use that endpoint as the signatureEndpoint prop.

Learn more about signing uploads.

Or see a full example of an API endpoint used with the Astro Cloudinary docs: https://github.com/cloudinary-community/astro-cloudinary/

Upload Events

The Cloudinary Upload Widget emits a series of events throughout the upload lifecycle. Some of those events include adding an asset, starting the upload queue (in the event of multiple uploads), and upon successful upload.

You can add callbacks for these events by adding an event listener to widget instance based on an associated ID.

For instance, to listen for the successful upload of an asset, you can add:

Upload

---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget
  id="upload-events"
  uploadPreset="<Your UploadPreset>"
/>

<script>
const widget = document.querySelector('#upload-events');

if ( widget ) {
  widget.addEventListener('clduploadwidget:success', ((e: CustomEvent<{ detail: object }>) => {
    console.log('clduploadwidget:success', e.detail);
    // {
    //  event: '<Event>',
    //  info: '<Cloudinary Resource>',
    //  UploadWidget // Widget Instance,
    // }
  }) as EventListener);
}
</script>

• Expand Snippet
• Collapse Snippet

Tip

See the web console for an example event.

To see a complete list of events and the corresponding shape of results, visit the Cloudinary Upload Widget API Reference.

The events are triggered with a pattern of clduploadwidget:<event>.

All events include a reference to the Upload Widget instance, which exposes instance methods such as open and close.

widget.addEventListener('clduploadwidget:queues-end', ((e: CustomEvent<{ detail: { UploadWidget: object } }>) => {
  e.detail.UploadWidget.close();
});

To see a full list of instance methods, visit the Cloudinary Upload Widget API Reference.

Learn More about CldUploadWidget

• Configuration
• Examples