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.
| Symbol | Purpose | Guide |
|---|---|---|
scope | Picks the cells that Replace covers | Find and replace |
replaceAllLimit | Caps the cells one Replace all changes | Find and replace |
processReplace | Checks or changes the plan before it writes | Find and replace |
findScope | Steps Next and Previous through the whole server result | Find and replace |
className | Adds classes to the panel root | Find and replace |
open | Opens the panel | Find and replace |
close | Closes the panel | Find and replace |
planReplace | Plans the changes and writes nothing | Find 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.
| Command | Default key | Result |
|---|---|---|
openFindReplace | Shift+Alt+Enter | Opens the panel with Replace. In a readOnly grid, it opens Find only |
openFind | Mod+F | Opens 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:
| Reason | Cause |
|---|---|
readonly | The column or row blocks writes, or the column has no accessorKey or setValue |
unparseable | The new text cannot become a value of the cell type |
too-long | The new text exceeds 100,000 characters |
no-occurrence | The cell matched, but its text holds no occurrence of the find text |
remaining
If the limit stops the scan while more cells match, remaining is true.