use-cloudinary-docs

useUpload

Table of Contents

The useUpload hook combined with a serverless function allows you to upload your files with ease to your Cloudinary account.

import { useUpload } from 'use-cloudinary'
function SignedUpload() {
  const {upload, data, isLoading, isError, error } = useUpload({ endpoint: "/your/endpoint" });
  if (isLoading) return <p>Loading...</p>;
  if (isError) return <p>{error.message}</p>;
  return (
    <div>
      <input type="file" onChange={() => {
        // ...stuff to make sure your media is ready to upload 
        upload({
          file,
          uploadOptions 
        });
      }} />
      {data && <img src={data.url} />}
    </div>
  )
}
function UnsignedUpload() {
  const {upload, data, status, error } = useUpload({ endpoint: "/your/endpoint" });
  if (isLoading) return <p>Loading...</p>;
  if (isError) return <p>{error.message}</p>;
  return (
    <div>
      <input type="file" onChange={() => {
        // ...stuff to make sure your media is ready to upload 
        upload({
          file,
          uploadOptions,
          // the only difference for unsigned uploads are these two keys. these will inform a backend function on which function from the SDK to use
          unsigned: "true",
          uploadPreset: "upload-preset-1"
        });
      }} />
      {data && <img src={data.url} />}
    </div>
  )
}

An example serverless function you'd set up looks like this --

const cloudinary = require('cloudinary').v2;
cloudinary.config({
  cloud_name: process.env.CLOUD_NAME,
  api_key: process.env.API_KEY,
  api_secret: process.env.API_SECRET
})
// When doing a signed upload, you'll use a function like this
exports.handler = (event) => {
  const { file } = JSON.parse(event.body);
  const res = await cloudinary.uploader.upload(file, { ...JSON.parse(event.body);})
  return {
    statusCode: 200,
    body: JSON.stringify(res)
  }
}
// When doing unsigned, you'll want to use a function like this one
exports.handler = event => {
  const { file } = JSON.parse(event.body);
  
  // The difference of using an unsigned uploads comes down to the options it accepts for the upload
  const res = await cloudinary.uploader.unsigned_upload(file, {...JSON.parse(event.body)});
  return {
    statusCode: 200,
    body: JSON.stringify(res)
  }
}

Args

KeyTypeRequired?Description
endpointStringYesAn endpoint that will accept your file and options and upload to Cloudinary

Return values

KeyTypeDescription
uploadFuncAn async function that that will pass our file and any transform options to our serverless function
dataundefined || StringWhen upload is successful, data will return the value of the request. More about this here
isLoadingBoolean isLoading state returns a boolean if the query is in a "hard" loading state. This means no cached data and the query is currently fetching.here
isErrroBooleanisError returns a boolean (true) if the query attempt resulted in an error (otherwise false). More about React Query return vairables here
isSuccessBooleanisSuccess returns a boolean (true) if the query attempt resulted in an error (otherwise false).More about React Query return vairables here
isIdleBooleanisIdle returns a boolean (true) if the query is initialized with enabled: false and no initial data is available (otherwise false). More about React Query return vairables here
errorObjectWhen upload is successful, data will return an object with details about your successfully uploaded media. More about that structure can be found here

upload()

The upload function is simply a setState call to pass your file and transformation options to our endpoint.

KeyTypeRequired?Description
fileStringYesThe file to upload. It can be:
  • a local file path (supported in SDKs only)
  • the actual data (byte array buffer). For example, in some SDKs, this could be an IO input stream of the data (e.g., File.open(file, "rb")).
  • the Data URI (Base64 encoded), max ~60 MB (62,910,000 chars)
  • the remote FTP, HTTP or HTTPS URL address of an existing file
  • a private storage bucket (S3 or Google Storage) URL of a whitelisted bucket
For details and examples, see: data upload options.
uploadOptionsObjectThe `uploadOptions` object is how you'll pass configuration to your serverless endpoint. For all of the options look here

Check this out for a full list of optional parameters.

Edit this page on GitHub

Prev

useVideo

Next

useSearch