Skip to content

Commit

Permalink
Merge pull request #10135 from marmelab/update-ra-search-doc
Browse files Browse the repository at this point in the history 
[Doc] Update ra-search documentation to mention disableHighlight
  • Loading branch information
@fzaninotto
fzaninotto authored Aug 8, 2024
2 parents 756cc0f + b0aff2c commit 37ca014
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 15 deletions.
40 changes: 31 additions & 9 deletions docs/Search.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -169,8 +169,9 @@ The `<Search>` component accepts the following props:
| Prop | Required | Type | Default | Description |
| -------------- | -------- | --------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| `children` | Optional | `Element` | `<SearchResultsPanel>` | A component that will display the results. |
| `color` | Optional | `string` | `light` | The color mode for the input, applying light or dark backgrounds. Accept either `light` or `dark`. |
| `disableHighlight` | Optional | `boolean` | `false` | Disable the highlight of the search term of each result. |
| `historySize` | Optional | `number` | 5 | The number of past queries to keep in history. |
| `isInAppBar` | Optional | `boolean` | `true` | Apply a dedicated style to the `<AppBar>` if true |
| `options` | Optional | `Object` | - | An object containing options to apply to the search. |
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v3/docs/react/reference/useQuery) | - | `react-query` options for the search query |
| `wait` | Optional | `number` | 500 | The delay of debounce for the search to launch after typing in ms. |
Expand Down Expand Up @@ -219,14 +220,16 @@ export const App = () => (
);
```

## `color`
### `disableHighlight`

If you need it, you can choose to render the `light` or the `dark` version of search input.
The search terms in each result are highlighted. You can disable this feature with the `disableHighlight` prop as follows:

```tsx
<Search color="dark" />
<Search disableHighlight />
```

**Tip:** To customize the highlight style check out the [Customizing the result items](#customizing-the-result-items) section below.

## `historySize`

The number of previous user searches to keep in the popover. For example, if a user performs 10 searches and `historySize` is set to 5, the popover will display the user's last 5 queries.
Expand Down Expand Up @@ -268,11 +271,12 @@ The number of milliseconds to wait before processing the search request, immedia
<Search wait={200} />
```

## Customizing The Result Items

### Customizing The Result Items

By default, `<Search>` displays the results in `<SearchResultsPanel>`, which displays each results in a `<SearchResultItem>`. So rendering `<Search>` without children is equivalent to rendering:

```jsx
```tsx
const MySearch = () => (
<Search>
<SearchResultsPanel>
Expand All @@ -286,7 +290,7 @@ const MySearch = () => (

For instance:

```jsx
```tsx
import {
Search,
SearchResultsPanel,
Expand Down Expand Up @@ -315,11 +319,11 @@ const MySearch = () => (

You can also completely replace the search result item component:

```jsx
```tsx
import { Search, SearchResultsPanel } from '@react-admin/ra-search';

const MySearchResultItem = ({ data, onClose }) => (
<li key={data.id}>
<li key={data.id} className="highlight">
<Link to={data.url} onClick={onClose}>
<strong>{data.content.label}</strong>
</Link>
Expand All @@ -336,6 +340,24 @@ const MySearch = () => (
);
```

**Tip:** You can customize the highlight of the search terms by overriding the `<SearchResultsPanel sx>` prop as following:

{% raw %}
```jsx
const CustomSearch = () => (
<Search>
<SearchResultsPanel
sx={{
'& ::highlight(search)': {
backgroundColor: '#7de5fa',
},
}}
/>
</Search>
);
```
{% endraw %}

## Customizing the Entire Search Results

Pass a custom React element as a child of `<Search>` to customize the appearance of the search results. This can be useful e.g. to customize the results grouping, or to arrange search results differently.
Expand Down
32 changes: 26 additions & 6 deletions docs/SearchWithResult.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Check [the `ra-search` documentation](https://react-admin-ee.marmelab.com/docume
| Prop | Required | Type | Default | Description |
| ------------ | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `children` | Optional | `Element` | `<SearchResultsPanel>` | A component that will display the results. |
| `color` | Optional | `string` | The opposite of theme mode. If mode is `light` default is `dark` and vice versa | The color mode for the input, applying light or dark backgrounds. Accept either `light` or `dark`. |
| `disableHighlight` | Optional | `boolean` | `false` | Disable the highlight of the search term of each result. |
| `onNavigate` | Optional | `function` | `() => undefined` | A callback function to run when the user navigate to a result. |
| `options` | Optional | `Object` | - | An object containing options to apply to the search. |
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v3/docs/react/reference/useQuery) | - | `react-query` options for the search query |
Expand Down Expand Up @@ -144,14 +144,16 @@ export const App = () => (
);
```

## `color`
### `disableHighlight`

If you need it, you can choose to render the `light` or the `dark` version of search input.
The search terms in each result are highlighted. You can disable this feature with the `disableHighlight` prop as follows:

```tsx
<SearchWithResult color="light" />
<SearchWithResults disableHighlight />
```

**Tip:** To customize the highlight style check out the [Customizing the result items](#customizing-the-result-items) section below.

## `onNavigate`

`onNavigate` allows you to perform an action when the user clicks on a search result, e.g. to close a menu ([See below](#use-it-with-solarlayout) for an example with `<SolarLayout>`).
Expand Down Expand Up @@ -260,7 +262,7 @@ export const App = () => (
```
{% endraw %}

## Customizing The Result Items
### Customizing The Result Items

By default, `<SearchWithResult>` displays the results in `<SearchResultsPanel>`, which displays each results in a `<SearchResultItem>`. So rendering `<SearchWithResult>` without children is equivalent to rendering:

Expand Down Expand Up @@ -335,7 +337,7 @@ import {
import { searchDataProvider } from './searchDataProvider';

const MySearchResultItem = ({ data }) => (
<li key={data.id}>
<li key={data.id} className="highlight">
<Link to={data.url}>
<strong>{data.content.label}</strong>
</Link>
Expand All @@ -362,6 +364,24 @@ export const App = () => (
);
```

**Tip:** You can customize the highlight of the search terms by overriding the `<SearchResultsPanel sx>` prop as following:

{% raw %}
```jsx
const CustomSearch = () => (
<SearchWithResult>
<SearchResultsPanel
sx={{
'& ::highlight(search)': {
backgroundColor: '#7de5fa',
},
}}
/>
</SearchWithResult>
);
```
{% endraw %}

## Use It With SolarLayout

The `<SearchWithResult>` component works perfectly when used inside the [`<SolarLayout>`](https://react-admin-ee.marmelab.com/documentation/ra-navigation#solarlayout) menu.
Expand Down

0 comments on commit 37ca014

Please sign in to comment.