useSearch
3 min read
The
useSearch hook provides access to the search context managed by the SearchProvider component. It enables reading and modifying the search state, such as sorting criteria, selected facets, and pagination. Use this hook to build interactive search features like sorting dropdowns, facet filters, and pagination controls.Import
_10import { useSearch } from '@faststore/sdk'
Usage
The following example shows how to implement a sorting dropdown using
useSearch:
_36import { useSearch } from '@faststore/sdk'_36_36// Example: A sort dropdown to change the search sorting criteria_36_36const keyMap = {_36 price_desc: 'Price, descending',_36 price_asc: 'Price, ascending',_36 orders_desc: 'Top sales',_36 name_asc: 'Name, A-Z',_36 name_desc: 'Name, Z-A',_36 release_desc: 'Release date',_36 discount_desc: 'Discount',_36 score_desc: 'Relevance',_36}_36_36const keys = Object.keys(keyMap)_36_36function Component () {_36 const {_36 setSort,_36 state: { sort },_36 } = useSearch()_36_36 return (_36 <select_36 onChange={(e) => setSort(keys[e.target.selectedIndex])}_36 value={sort}_36 >_36 {keys.map((key) => (_36 <option key={key} value={key}>_36 {keyMap[key]}_36 </option>_36 ))}_36 </select>_36 )_36}
useSearch: Accesses the search context to read and update the search state.
keyMap: Maps sorting keys to user-friendly labels.
setSort: Updates the sorting criteria.
sort: Contains the current sorting criteria from the search state.API reference
The
useSearch hook returns an object with the following properties and functions:| Variable name | Data type | Description |
|---|---|---|
itemsPerPage | number | Number of items displayed per page. |
state | SearchState | Contains the current state of the search, including selected facets, sorting criteria, and pagination. |
setSort | (sort: SearchSort) => void | Updates the sorting criteria of the search results. |
setTerm | (term: string / null) => void | Updates the full-text search term. |
setPage | (page: number) => void | Updates the current page in the search pagination. |
removeFacet | (facet: Facet) => void | Removes a specific facet from the search state. |
toggleFacet | (facet: Facet) => void | Toggles a specific facet in the search state. If the facet is already selected, it will be removed; otherwise, it will be added. |
toggleFacets | (facets: Facet[]) => void | Toggles multiple facets in the search state. |
addPrevPage | () => void | Prepends a page of results to the current list (used in infinite scroll). |
addNextPage | () => void | Appends a page of results to the current list (used in infinite scroll). |
Custom sort values
parseSearchState accepts only the built-in sort keys until the storefront adds more with registerCustomSortKeys. Call it once, before the search page reads the URL. Use the same key in the GraphQL StoreSort extension and in api.customSortMap.
_10import { registerCustomSortKeys } from '@faststore/sdk'_10_10registerCustomSortKeys(['rating_desc'])
After this call, a URL such as
/?sort=rating_desc keeps that sort on refresh and on a deep link. A key that was not added still throws when the URL is parsed.Add the same key to the sort control
keyMap when the option should appear in the UI. The full procedure is in Adding a custom search sort.