saturation/uiInstallation
pnpm dlx shadcn@latest add @saturation-ui/detail-fieldTailwind v4 — Source Scanning
The public shadcn registry installs component source into your project. If Tailwind v4 isn't scanning your components directory, add this to your CSS entry file:
@source "../components";This ensures all utility classes in CVA variants and data attribute selectors are included in your build.
Usage
import {
DetailField,
type FieldDef,
} from "@/components/ui/detail-field"<DetailField
def={{ label: "Status", icon: <CircleDotIcon />, kind: "select", options: STATUS_OPTS }}
value={record.status}
onChange={(v) => update("status", v)}
/>Not the shadcn form Field family — that is vertical form anatomy. DetailField is the detail-panel ROW: icon + 140px label column + value cell + hover affordances.
Sub-parts
EditableText (inline click-to-edit text/textarea: hover pencil, Enter/Escape semantics, debounced autosave, link mode) and PanelEditorCell (click-to-edit host for self-anchoring popover editors) are the field's editor primitives. They are exported from the package and installable via the CLI (editable-text, panel-editor-cell) but are implementation detail of the field system, not standalone surface.
API Reference
Def mode
| Prop | Type | Default | Description |
|---|---|---|---|
def | FieldDef | — | The field definition: label, icon, kind (text · longtext · email · phone · url · date · currency · select · ref · tags · unit), state (editable · readonly · computed), plus inline affordances (lock, source, navTo, tint) and editor payload (options / entities / search). Unavailable in children mode. |
value | FieldValue | — | Controlled value (string, RefValue, or TagsValue). |
onChange | (v: FieldValue) => void | — | Change handler. |
onOpen | (id: string) => void | — | Fired when a ref field's name link is clicked (deep-link). |
editors | DetailFieldEditors | — | Injected editors for the data-coupled kinds (date / ref / tags / unit). Without one, the kit renders a formatted read-only value and warns in dev. Apps typically bake these into a wrapper once. |
Children mode (row anatomy)
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Custom value cell — the row anatomy (icon + 140px label + hover affordances) is unchanged. Mutually exclusive with def at the type level. |
label | string | — | Row label (falls back to def.label in def mode). |
icon | ReactNode | — | Row icon, normalized to 15px (falls back to def.icon). |
isLocked / lockReason / onUnlock | … | — | Hover lock affordance with optional click-to-unlock. |
copyValue | string | — | Hover copy button (auto-derived in def mode: email/phone always; non-editable scalars). |
onView / viewLabel | … | — | Hover deep-link (↗) affordance. |
aiMarker / aiBeam / aiBeamActive | … | — | Provenance marker slot + fill-choreography beam. |
computed | boolean | — | Muted non-editable tint on the value cell. |