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
| Parameter | Type | Description |
|---|---|---|
apiKeyrequired | string | Your public API key. |
collectionsrequired | string[] | Collections to search. |
queryrequired | string | Controlled query string. |
limit | number | Max results (default: 10). |
offset | number | Pagination offset (default: 0). |
debounceMs | number | Debounce delay in ms (default: 100). |
shouldRetryOnError | boolean | Retry failed requests automatically (default: true). |
errorRetryCount | number | Maximum retries after a failed request (default: 2). |
errorRetryInterval | number | Delay between retries in ms (default: 1000). |
filters | SearchFilter[] | Apply explicit metadata filters. |
autoFilters | boolean | Let AI extract filters from the query. |
Returns
| Parameter | Type | Description |
|---|---|---|
results | SearchResult[] | Last successful results. |
isLoading | boolean | True while a request is in flight. |
error | unknown | Error from the last request, if any. |
isError | boolean | True when the last request failed. |
appliedFilters | SearchFilter[] | undefined | Filters applied to the request. |
refinedQuery | string | undefined | AI-refined query when autoFilters is enabled. |