gridcn2.0.0
Add-on optionsSort, filter, and search

Find and replace options

Look up the options of useDataGridFindReplace, the open and close methods it returns, and the planReplace function.

useDataGridFindReplace returns a plugin that mounts the find and replace panel. It also returns open and close methods for your own buttons. The planReplace function builds the list of changes without writing them.

SymbolPurposeGuide
scopePicks the cells that Replace coversFind and replace
replaceAllLimitCaps the cells one Replace all changesFind and replace
processReplaceChecks or changes the plan before it writesFind and replace
findScopeSteps Next and Previous through the whole server resultFind and replace
classNameAdds classes to the panel rootFind and replace
openOpens the panelFind and replace
closeCloses the panelFind and replace
planReplacePlans the changes and writes nothingFind and replace

useDataGridFindReplace

This sample passes the plugin to the grid:

import {
  DataGrid,
  defineColumns,
} from "@/components/data-grid/data-grid";
import {
  useDataGridFindReplace,
} from "@/components/data-grid-find-replace/data-grid-find-replace";

type Person = { id: string; name: string };

const people: Person[] = [{ id: "1", name: "Ada" }];

const columns = defineColumns<Person>()([
  { id: "name", accessorKey: "name", header: "Name" },
]);

export function PeopleGrid() {
  const findReplace = useDataGridFindReplace({ replaceAllLimit: 500 });

  return (
    <DataGrid
      defaultData={people}
      columns={columns}
      plugins={[findReplace.plugin]}
    />
  );
}

Prop

Type

processReplace

Runs after the panel builds the plan and before it writes. It gets { plan, signal } and returns the plan to write, or false to cancel. A string patch for a non-string cell runs through fromText, and the grid skips an unparseable one. The column validate runs on every patch. A plan longer than replaceAllLimit, a value that is not a plan, or a rejection cancels the replace. So does a patched row that changes or goes away, a readOnly grid, or an open cell editor. A change of the find text, the replacement, or an option aborts signal.

scope

"view" covers every visible column of the rows in the view. On a client-paged grid, it covers every page. In pages mode of a server grid, it covers the shown page. In scroll mode, it covers the loaded rows. See Find and replace: Server mode. "selection" covers only the selected cells.

replaceAllLimit

planReplace clamps the value to 1 through 100,000. The default is 10,000. When more cells match, Replace all changes the first cells up to the limit. A second click skips the cells the first click changed and continues.

findScope

"loaded" steps through the matches of the loaded rows. "result" states that the server narrows the result by spec.searchText. The count line then shows the size of the result. Next and Previous go on into unloaded rows: scroll mode scrolls to the next block, and pages mode asks for the next page. Replace and Replace all stay on loaded rows. In pages mode, the panel reads the pager through useStashedPager.

className

Merged with cn into the class list of the panel root. The panel root sets the width, the corners, the background, and the shadow, so a class here overrides them.

Result

Prop

Type

open

open("replace") is the default. It shows the Replace field. open("find") shows the Find field only. In a readOnly grid, the Replace buttons stay disabled.

close

close() closes the panel.

Commands and keys

The plugin registers two commands. Remap them with the keymap prop of the grid.

CommandDefault keyResult
openFindReplaceShift+Alt+EnterOpens the panel with Replace. In a readOnly grid, it opens Find only
openFindMod+FOpens the panel with Find only

planReplace

planReplace(state, find, replacement, options?) takes a ReplaceState and returns a ReplacePlan: { patches, skipped, remaining }. It reads the grid state and writes nothing. This button passes patches to updateCells to write them:

import { useDataGridApi } from "@/components/data-grid/data-grid";
import {
  planReplace,
} from "@/components/data-grid-find-replace/data-grid-find-replace";

export function ReplaceButton() {
  const api = useDataGridApi();

  return (
    <button
      type="button"
      onClick={() => {
        const plan = planReplace(api.store.getState(), "Ada", "Grace");
        api.actions.updateCells(plan.patches, { source: "replace" });
      }}
    >
      Replace Ada
    </button>
  );
}

Render the button inside DataGridProvider. planReplace cuts the find text and the replacement to 1,000 characters. It trims spaces at both ends of the find text.

Prop

Type

planReplace also takes only, a { rowId, columnId } cell. With only, the plan covers that cell.

skipped

Each entry of skipped holds a cell and a reason. The reason is a ReplaceSkipReason:

ReasonCause
readonlyThe column or row blocks writes, or the column has no accessorKey or setValue
unparseableThe new text cannot become a value of the cell type
too-longThe new text exceeds 100,000 characters
no-occurrenceThe cell matched, but its text holds no occurrence of the find text
hiddenA processReplace patch targets a hidden column. The panel does not write it

remaining

If the limit stops the scan while more cells match, remaining is true.

On this page