gridcn2.0.0
Sort, filter, and search

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.

1/15
Name
Email
Role
Silent Tiger
user0@example.com
Viewer
Quick Lion
user1@example.com
Viewer
Swift Wolf
user2@example.com
Manager
Eager Lion
user3@example.com
User
Eager Tiger
user4@example.com
Viewer
Silent Wolf
user5@example.com
User
Swift Lion
user6@example.com
Viewer
Eager Lion
user7@example.com
Manager
Eager Eagle
user8@example.com
Editor
Bold Tiger
user9@example.com
Editor
Bold Bear
user10@example.com
User
Swift Wolf
user11@example.com
Manager
Swift Bear
user12@example.com
Viewer
Eager Wolf
user13@example.com
Editor
Swift Eagle
user14@example.com
Viewer
Quick Lion
user15@example.com
Manager
Bold Wolf
user16@example.com
Editor
Swift Eagle
user17@example.com
Admin
Eager Eagle
user18@example.com
Manager
Eager Bear
user19@example.com
Editor
Silent Lion
user20@example.com
Manager
Silent Tiger
user21@example.com
Manager
Eager Tiger
user22@example.com
Manager
Silent Lion
user23@example.com
Admin
Bold Eagle
user24@example.com
Admin
Bold Lion
user25@example.com
Viewer
Quick Tiger
user26@example.com
Viewer
Bold Eagle
user27@example.com
Editor
Swift Tiger
user28@example.com
Editor
Silent Lion
user29@example.com
Viewer

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>
  );
}

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.

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.

KeyAction
EnterGoes to the next match. When typed text is still waiting, it commits the text and goes to the first match.
Shift+EnterGoes to the previous match.
EscapeClears the text and the search.
Mod+FFocuses 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.

PropTypeDefaultDescription
placeholderstringlabels.toolbar.searchPlaceholderPlaceholder text.
debounceMsnumberthe grid's inputDebounceMsTyping delay in ms.
classNamestringnoneClasses 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.

On this page