use-cloudinary-docs

useSearch

Table of Contents

Combining our useSearch hook with a serverless endpoint will let you create different ways to call multiple or individual assets, based off of a handful of different possibilities. 

import Image from './Image';
import { useSearch } from 'use-cloudinary';
export default function Images({ endpoint }) {
  const { search, data, isLoading, isError, error } = useSearch({ endpoint });
 
  if (isLoading) return <p>Loading...</p>;
  if (isError) return <p>{error.message}</p>;
  // OPTION 1: To mirror Cloudinary's Node SDK's search expression, we've provided direct support for crafting custom search queries
  const expressionSearch = search({ expression: "resource_type:image"})
  // OPTION 2: Also included is a few opinionated object configurations to more easily craft search based off of user interaction. This includes publicId search, folder search, and more. 
  const customConfigSearch = search({ resourceType: "image" }) 
  return (
    <div>
      <button onClick={() => expressionSearch()}>Load</button>
      <div>
        {
          data && data.resources.map(image => (
            <Image publicId={image.public_id} transforms={{ height: 0.2, border: "2px_solid_black" }} />
          )}
      </div>
    </div >
  )

Combined with this serverless endpoint example, we can get all of the images in our Cloudinary account, by utilizing search expressions and looking for all images. Cloudinary's Search API let's you search your assets a bunch of different ways!

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
})
exports.handler = async (event) => {
  const body = JSON.parse(event.body);
  const res = await cloudinary.search
    .expression(body.expression)
    .execute().then(result => result);
  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
searchFuncAn async function that accepts options and returns an array of objects or single object, describing your Cloudinary assets
dataundefined || StringWhen `search` is successful, data will return the value of the request. 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
errorObjectWhen getVideo is successful, data will return the value of the request, usually a String defining your asset URL. More about React Query's return values here

Our search function simply can accept any of the options you would expect to send to the Search API. There's also been added support to setup an opinionated search using a custom object configuration.

Mostly, the search will be handled in your serverless function, so whatever you support there is available to your hook's search.

Including no parameters in the method call will return the 50 most recently created resources in descending order of creation time.

Otherwise your options are --

KeyTypeRequiredDescription
publicIdStringNoThe public id of the asset to search for. Supports only exact matches currently. Case sensitive.
resourceTypeStringNoPossible values: image & video. Exact match only. Case sensitive.
folderStringNoSearch for an exact folder path. Case sensitive.
tagsStringNoSearch for images by tag(s). The tags should be in a single string seperated by spaces. Case sensitive
aspectRatioStringNoSpecify an image ratio in a string with "Width:Height" Exact match and case sensitive.
expressionStringNoDescribes the query string for filtering the assets in your account. Learn more here
sort_byStringNoA key value pair, where the key is the field to sort by and the value is the direction
max_resultsIntNoThe maximum number of results to return. Default is 50, maximum is 500
next_cursorStringNoWhen a search request returns more results than max_results, the next_cursor value is returned as part of the response.
with_fieldStringNoYou can have multiple with_field parameters with possible values of context and tags

Be aware of your Usage Limits

Edit this page on GitHub

Prev

useUpload