Quick search
Add a search box that highlights matching cells, jumps between them, and never hides rows.
Users type a word and the grid highlights every cell that holds it. DataGridSearch is the input. It counts the matches, and it moves the active cell from match to match. Search never hides rows. A filter hides rows.
DataGridSearch comes with the toolbar add-on. Put it first in the toolbar:
"use client";
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
defineColumns,
} from "@/components/data-grid/data-grid";
import {
DataGridSearch,
DataGridToolbar,
} from "@/components/data-grid-toolbar/data-grid-toolbar";
type Person = { id: string; name: string; city: string };
const columns = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name" },
{ id: "city", header: "City", accessorKey: "city" },
]);
export function PeopleGrid({ rows }: { rows: Person[] }) {
return (
<DataGridProvider
defaultData={rows}
columns={columns}
defaultSearchText="ams"
>
<DataGridToolbar>
<DataGridSearch placeholder="Find a person" />
</DataGridToolbar>
<DataGridRoot className="h-96">
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}What search matches
The search is a literal text match that ignores case by default. It ignores spaces at both ends of the text. It reads the visible columns of the rows in the current view. A filtered-out row is not searched.
The search reads each cell as its search text. That is the toSearchText of its cell type, or else its toText. A column without a registered type matches its raw value as text. The built-in select type declares toSearchText, so a select column matches the choice label. Its filters match the stored value.
actions.setSearch(text, { matchCase, wholeCell }) sets the search options. matchCase respects letter case. wholeCell matches only cells that equal the text. Both default to false and stay set across later searches. The find and replace panel sets them.
Search keeps at most 1,000 matches. Past that cap the counter reads the current match and 1000+, for example 3/1000+. Set that text with labels.toolbar.searchMatchesCapped.
Navigate matches
The counter shows current/total, and 0/0 when nothing matches. The next and previous buttons wrap around. A jump moves the active cell to the match and scrolls it into view. In a client grid that pages its view, the counter covers every page. The highlight marks the matches on the shown page. A jump to a match on another page changes the page.
Focus stays in the search field while Enter steps through the matches, so the next Enter goes to the next match. To move focus into the grid, call api.focus() on the grid ref.
| Key | Action |
|---|---|
| Enter | Goes to the next match. When typed text is still waiting, it commits the text and goes to the first match. |
| Shift+Enter | Goes to the previous match. |
| Escape | Clears the text and the search. |
| Mod+F | Focuses the input, or selects its text when it has focus. |
Mod+F works while focus is inside the grid or its toolbar. Anywhere else on the page, the browser's own find opens. Several grids on one page each take the key when they hold focus. When a toolbar you build yourself carries the data-grid-toolbar attribute and contains the DataGridSearch, it counts as part of the grid. Native find cannot see rows that virtualization has not rendered, so the grid takes the key.
The key is the focusSearch action of the keymap. To keep the browser's find in the grid, set keymap={{ focusSearch: [] }}. To use another key, set keymap={{ focusSearch: ["mod+j"] }}. Without a DataGridSearch on screen, the browser keeps the key.
With the find and replace add-on mounted, Mod+F opens its panel instead, and focusSearch has no default key. Bind focusSearch in your keymap to focus the toolbar input with another key. Both show the same search text.
Typing delay
The input waits inputDebounceMs after the last keystroke before it searches. The provider prop defaults to 200. 0 searches on each keystroke. The wait also applies to the filter value inputs, the header filter search, the find and replace field, and the lookup editor. debounceMs on DataGridSearch overrides it for one box.
Typed text is not lost. Blur, Enter, and unmount commit text that is still waiting. While an IME composes, the wait does not run. Blur and unmount commit the text so far, and the composed text commits when the composition ends. See useDebouncedInput.
| Prop | Type | Default | Description |
|---|---|---|---|
placeholder | string | labels.toolbar.searchPlaceholder | Placeholder text. |
debounceMs | number | the grid's inputDebounceMs | Typing delay in ms. |
className | string | none | Classes for the root. |
defaultSearchText seeds the text once. searchText and onSearchTextChange(next) control it.
Server mode
Search has no server mode. It highlights and navigates the rows the grid holds, in every data mode. In scroll mode, rows that are not loaded yet are not searched. sortMode and filterMode do not change this.
useDataGridServerRows puts the search text in each request as request.spec.searchText. Your server can narrow the rows by it. The grid still only highlights the rows that come back.
Related
- Toolbar: where the input sits
- Find and replace: search with replace
- Filtering: hide rows by value
- Toolbar options: the full prop list