Duplicate guard

A React component in Beamline's Data & tables category.

A new record that watches for the one that already exists: as you type, the likely duplicates slide in beside the form with the fields that match lit and said in words (Number plate · same, Name · similar), strongest first. Use the existing record, merge what you typed into it (both fold into one column, agreements read once, every difference a choice with the existing value first, nothing lost) or say Not them; Create stays offered and becomes the main action when nothing matches.

Use it for

Creating a customer, contact, patient, member or vehicle where the same one may already exist under another spelling: garages, clinics, help desks, CRMs, school offices.
The host passes the records to look in (or the ones its own search found) and owns what Use, Merge and Create do; the part compares, explains and builds the merged values.

Not for

Mapping columns of an imported file to fields → import-mapping; fixing an imported file's rows → import-lens.
Searching a list to pick one item → combobox or command-palette.

Anatomy

form: the label, one field per GuardField; a field that matches a shown card carries a lit mark; Create {name} (Create new while no name)
matches: Possible matches; up to three cards, strongest first; a card: the record's name and detail, its reasons as chips (same filled, similar outlined), Use / Merge / Not them; and N more possible
merge (inside its card): What {name} will have, one row per field: Same in both, kept, from what you typed, or a choice of two (the existing value first); Merge into {name} / Cancel
done: Merged into / Created / Using {name}

States

empty
typing (matches arrive)
a match (same)
a match (similar)
more than three
merging
a card put aside
no matches
merged
created
used

Keyboard

The fields are ordinary inputs; each card is a region named by its record and Tab reaches Use, Merge and Not them
In the merge, each difference is a radio group of two; Escape closes the merge and returns to the card's Merge
Not them moves focus to the next card's first action, or to Create; arriving matches are said once (a polite status)

Motion

A card slides in where it belongs, moves when it rises past another, and leaves as a ghost; the merge rows grow out of the reason chips they came from (the shared FLIP). A field's lit mark grows in. Nothing runs at rest; reduced motion places everything.

Props

Prop	Type	Default	Description
`label` (required)	`string`	—	What is being created: "New customer".
`fields` (required)	`GuardField[]`	—
`records` (required)	`GuardRecord[]`	—	The records to look in (the host may pass the ones its own search found).
`value`	`Record<string, string>`	—	The draft, by field id.
`defaultValue`	`Record<string, string>`	—	Initial selection when uncontrolled; omitted by default.
`onValueChange`	`((draft: Record<string, string>) => void)`	—	Reports the selected value after a change; no callback by default.
`onUse`	`((record: GuardRecord) => void)`	—	Use an existing record instead of creating one (the host keeps the draft for it if it likes).
`onMerge`	`((record: GuardRecord, merged: Record<string, string>) => void \| Promise<unknown>)`	—	Merge what was typed into a record: the combined values, every difference chosen.
`onCreate`	`((draft: Record<string, string>) => void \| Promise<unknown>)`	—	Create the new record (always offered).
`match`	`((draft: Record<string, string>, record: GuardRecord) => GuardReason[])`	—	Replace the built-in comparison: the reasons a record matches the draft (none: not a match).
`limit`	`number`	—	How many cards at most; the rest are counted. Default 3.
`className`	`string`	—	Classes on the documented visual root; no override by default.
`classNames`	`Partial<Record<"root" \| "form" \| "card" \| "matches" \| "merge", string>>`	—	Classes for the named visual parts; no overrides by default.
`style`	`CSSProperties`	—	Inline styles on the documented visual root; no overrides by default.
`ref`	`Ref<HTMLDivElement>`	—	Receives the documented native target or imperative handle; omitted by default.

Built from

Dependencies

lucide-react

Import

import { DuplicateGuard } from "@beamline/duplicate-guard";

Get it

Duplicate guard is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Get Beamline · Connect your agent

Duplicate guardComplete system · $49

A new record that watches for the one that already exists.

A new customer at the garage

The man at the counter says Jon Smith and reads out his plate. Jonathan Smith slid in while the name was typed, and the plate matched his car exactly: it was serviced here two years ago. Merge keeps his history, takes the new email and asks which mobile; Not them puts a card aside.

0 × 0full

A help desk caller with a member number

The member number is the same, so María López leads; the name differs only in its accent. Merging asks which email to keep and adds the note from what was typed.

0 × 0full

Typing from empty

Nothing shows until there is something to compare: three letters of a name, seven digits of a phone, a plate. Type Jon Smi, then the plate LD17 XKA.

0 × 0full

Nobody like them

A name and a phone nobody has: no cards, and Create is the main action.

0 × 0full

About Duplicate guard

← Import lens Scan flow →

Part of Beamline UI: polished, editable React components and complete screens for custom applications. Build your own style from any look; tokens, fonts, radii, motion; not only colours.

Duplicate guard

Use it for

Not for

Anatomy

States

Keyboard

Motion

Props

Built from

Dependencies

Import

Get it

More in Data & tables