use-cloudinary-docs

useImage

The useImage hook gives you the ability to call an image from your Cloudinary account and apply transformations. The result is a URL generated by the SDK.

import { useImage } from 'use-cloudinary';
// Basic Image component
function Image({ publicId, transformations, width, height, alt }) {
const { generateUrl, url, isLoading, isError, error } = useImage({ cloudName: 'testing-hooks-upload' });
React.useEffect(() => {
// the `generateUrl` function will hook internally to the SDK and do a lot of the heavy lifting for generating your image url
generateUrl({
publicId,
transformations: {
// by supplying height and width separately from the transformations object,
// we can use the height and width to dictate the size of the element AND the transformations
height,
width,
// then we can spread the rest of the transformations in
...transformations
/*
you'll also be getting these automatically attached from internals
fetchFormat: 'auto',
quality: 'auto',
crop: 'scale'
*/
}
});
});
if (isLoading) return <p>Loading...</p>;
if (isError) return <p>{error.message}</p>;
return (
<img
style={{
height: `${height}px`,
width: `${width}px`
}}
src={url}
alt={alt}
/>
)
}
// Image w/ Lazy-load + placeholder
function Image({ publicId, transformations, width, height, cloudName }) {
const {
generateUrl,
blurredPlaceholderUrl,
url,
isError,
error,
ref,
supportsLazyLoading,
inView
} = useImage({ cloudName });
React.useEffect(() => {
generateUrl({
publicId,
transformations: {
width,
height,
...transformations
}
})
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [])
if (isError) return <p>{error.message}</p>;
return (
<div
ref={!supportsLazyLoading ? ref : undefined}
style={{
width: `${width}px`,
height: `${height}px`,
background: `no-repeat url(${blurredPlaceholderUrl(publicId, width, height)})`
}}>
{inView || supportsLazyLoading ? (
<img
src={url}
loading="lazy"
style={{
width: `${width}px`,
height: `${height}px`,
}}
alt="Lazy loaded"
/>
) : null}
</div>
)
}

Args

KeyTypeRequired?Description
cloudNameStringYesYour Cloudinary cloud name, used to identify where we're getting our media from

Return values

KeyTypeDescription
generateUrlFuncAn async function that accepts options and returns the URL of your Cloudinary asset
blurredPlaceholderUrlFuncThis function delivers your media in a low quality blur format, perfect for fallback placeholders while lazy-loading / initial load
urlundefined || StringWhen `generateUrl` is successful, url will return a URL string. More about React Query's return values 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
inViewBooleanThe inView boolean changes dependent on the elements 'ref' coming into the viewport.
refObjA ref is used to return a reference to the element, directly supports "inView"
supportsLazyLoadingBooleanReturns a boolean dependent on if the browser supports lazy-loading or not
errorObjectOn failure, React Query returns an error object, surfacing the error message for use in the UI. More about React Query's return values here

generateUrl()

The generateUrl function is just a setState, used to fire off our internal query and pass our options into our SDK to generate our URL.

KeyTypeRequiredDescription
publicIdStringYesThe public id is the name used as a title for the media you want to call. This can be a single string like "example" or include your folder structure like "test/example"
transformationsObjectNoCheck out all the transformations you can apply to your images here
Edit this page on GitHub