https://github.com/yext/search-headless-react
React UI bindings for the @yext/search-headless library
https://github.com/yext/search-headless-react
Last synced: 9 months ago
JSON representation
React UI bindings for the @yext/search-headless library
- Host: GitHub
- URL: https://github.com/yext/search-headless-react
- Owner: yext
- License: other
- Created: 2021-07-30T21:22:35.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-19T21:35:56.000Z (over 1 year ago)
- Last Synced: 2024-12-04T23:26:08.498Z (over 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 3.71 MB
- Stars: 6
- Watchers: 6
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Search Headless React
Search Headless React is the official React UI Bindings layer for [Search Headless](https://www.npmjs.com/package/@yext/search-headless).
Written in 100% TypeScript.
## Installation
```shell
npm install @yext/search-headless-react
```
## Getting Started - `SearchHeadlessProvider`
Search Headless React includes an `` component, which takes in a `SearchHeadless` instance and makes it available to the rest of your app. `SearchHeadless` instance is created using `provideHeadless(...)` with the appropriate credentials:
```tsx
import { provideHeadless, SearchHeadlessProvider } from '@yext/search-headless-react';
import SearchBar from './SearchBar';
import MostRecentSearch from './MostRecentSearch';
import UniversalResults from './UniversalResults';
const searcher = provideHeadless(config);
function MyApp() {
return (
{/* Add components that use Search as children */}
);
}
```
## Respond to State Updates with `useSearchState`
`useSearchState` reads a value from the `SearchHeadless` state and subscribes to updates.
```tsx
import { useSearchState } from '@yext/search-headless-react';
export default function MostRecentSearch() {
const mostRecentSearch = useSearchState(state => state.query.mostRecentSearch);
return
Showing results for {mostRecentSearch};
}
```
## Dispatch Actions with `useSearchActions`
`useSearchActions` allows you to dispatch actions using the `SearchHeadless` instance.
These include performing searches, getting autocomplete suggestions, and adding filters.
For a full list of capabilities see [the search-headless docs](https://www.npmjs.com/package/@yext/search-headless).
```tsx
import { useSearchActions } from '@yext/search-headless-react';
import { ChangeEvent, KeyboardEvent, useCallback } from 'react';
function SearchBar() {
const search = useSearchActions();
const handleTyping = useCallback((e: ChangeEvent) => {
search.setQuery(e.target.value);
}, [search]);
const handleKeyDown = useCallback((evt: KeyboardEvent) => {
if (evt.key === 'Enter' ) {
search.executeUniversalQuery();
}
}, [search]);
return ;
}
```
## `SearchHeadlessContext`
### Class Components
For users that want to use class components instead of functional components, you can use the `SearchHeadlessContext` directly to dispatch actions and receive updates from state.
As an example, here is our simple SearchBar again, rewritten as a class using `SearchHeadlessContext`.
```tsx
import { SearchHeadlessContext, SearchHeadless, State } from '@yext/search-headless-react';
import { Component } from 'react';
export default class Searcher extends Component {
static contextType = SearchHeadlessContext;
unsubscribeQueryListener: any;
state = { query: "" };
componentDidMount() {
const search: SearchHeadless = this.context;
this.unsubscribeQueryListener = search.addListener({
valueAccessor: (state: State) => state.query.mostRecentSearch,
callback: newPropsFromState => {
this.setState({ query: newPropsFromState })
}
});
}
componentWillUnmount() {
this.unsubscribeQueryListener();
}
render() {
const search: SearchHeadless = this.context;
return (
Query: {this.state.query}
search.setQuery(evt.target.value)}
onKeyDown={evt => {
if (evt.key === 'Enter') {
search.executeUniversalQuery();
}
}}
/>
)
}
}
```
## `useSearchUtilities`
We offer a `useSearchUtilities` convenience hook for accessing `SearchHeadless.utilities`, which offers a number of stateless utility methods.
The `searchUtilities` and `searchUtilitiesFromActions` variables below are equivalent.
For class components, you can access `SearchUtilities` through `SearchHeadlessContext`.
```ts
const searchUtilities = useSearchUtilities();
const searchUtilitiesFromActions = useSearchActions().utilities;
```