Hooks

Use useEtoileSearch when you want full control over rendering and data flow.


useEtoileSearch

query is controlled by your component.

import { useState } from "react";
import { useEtoileSearch } from "@etoile-dev/react";

export default function MySearch() {
const [query, setQuery] = useState("");

const { results, isLoading, isError } = useEtoileSearch({
  apiKey: process.env.NEXT_PUBLIC_ETOILE_PUBLIC_KEY,
  collections: ["paintings"],
  query,
  debounceMs: 120,
  shouldRetryOnError: true,
  errorRetryCount: 2,
  errorRetryInterval: 1000,
});

return (
  <div>
    <input
      value={query}
      onChange={(e) => setQuery(e.target.value)}
      placeholder="Search paintings…"
    />

    {isLoading && <p>Searching…</p>}
    {isError && <p>Something went wrong.</p>}

    <ul>
      {results.map((result) => (
        <li key={result.external_id}>{result.title}</li>
      ))}
    </ul>
  </div>
);
}

useSearch is an alias of useEtoileSearch.


Options

ParameterTypeDescription
apiKeyrequiredstringYour public API key.
collectionsrequiredstring[]Collections to search.
queryrequiredstringControlled query string.
limitnumberMax results (default: 10).
offsetnumberPagination offset (default: 0).
debounceMsnumberDebounce delay in ms (default: 100).
shouldRetryOnErrorbooleanRetry failed requests automatically (default: true).
errorRetryCountnumberMaximum retries after a failed request (default: 2).
errorRetryIntervalnumberDelay between retries in ms (default: 1000).
filtersSearchFilter[]Apply explicit metadata filters.
autoFiltersbooleanLet AI extract filters from the query.

Returns

ParameterTypeDescription
resultsSearchResult[]Last successful results.
isLoadingbooleanTrue while a request is in flight.
errorunknownError from the last request, if any.
isErrorbooleanTrue when the last request failed.
appliedFiltersSearchFilter[] | undefinedFilters applied to the request.
refinedQuerystring | undefinedAI-refined query when autoFilters is enabled.

Related

  • Setup — ready-to-use components
  • Styling — theme and data-attribute styling