Field
SaveA field wrapper that wires a label, control, description, and validation error together with Base UI Field, plus a fieldset group.
- Category
- Forms
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Field preview
Installation
npx @shakenui/cli add fieldReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add field --dry-runUsage
field-example.tsx
"use client";
import { Field, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldSeparator } from "@/components/shaken/ui/field";
import { Input } from "@/components/shaken/ui/input";
import { Textarea } from "@/components/shaken/ui/textarea";
export default function FieldExample() {
return (
<form className="grid w-full max-w-md gap-6" noValidate>
<FieldGroup legend="Agent" description="How this agent appears in runs and approval requests.">
<Field name="agentName" validationMode="onBlur">
<FieldLabel required>Name</FieldLabel>
<FieldControl render={<Input />} required placeholder="Release notes writer" />
<FieldDescription>Shown in run logs and in the approval inbox.</FieldDescription>
<FieldError match="valueMissing">Give the agent a name.</FieldError>
</Field>
<Field name="instructions">
<FieldLabel optional>Instructions</FieldLabel>
<FieldControl
render={<Textarea autoGrow maxLength={400} />}
placeholder="Summarize merged pull requests for the weekly changelog."
/>
</Field>
</FieldGroup>
<FieldSeparator />
<FieldGroup legend="Limits" className="sm:grid-cols-2">
<Field
name="maxSteps"
validationMode="onChange"
validate={(value) => (Number(value) > 50 ? "Keep it at 50 steps or fewer." : null)}
>
<FieldLabel>Max steps</FieldLabel>
<FieldControl type="number" inputMode="numeric" defaultValue="24" min={1} className="font-mono tabular-nums" />
<FieldError />
</Field>
<Field name="alertEmail" validationMode="onBlur">
<FieldLabel>Alert email</FieldLabel>
<FieldControl type="email" placeholder="oncall@northwind.dev" />
<FieldError match="typeMismatch">Enter a complete email address.</FieldError>
</Field>
</FieldGroup>
</form>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| validate | (value, formValues) => string | string[] | null | — | Field: custom validation. Return an error message to mark the field invalid. |
| validationMode | "onSubmit" | "onBlur" | "onChange" | "onSubmit" | Field: when to validate. |
| invalid | boolean | — | Field: forces the invalid state, for errors from a server or a form library. |
| disabled | boolean | false | Field or FieldGroup: disables the control(s) inside. |
| required / optional | boolean | false | FieldLabel: adds a required asterisk or an Optional note. |
| render | ReactElement | — | FieldControl: render the existing Input or Textarea, e.g. render={<Input />}. Without it, a text input styled like Input is rendered. |
| match | boolean | keyof ValidityState | — | FieldError: show only for one validity check, or always with true. |
| legend / description | ReactNode | — | FieldGroup: names the fieldset and describes the group. |
Accessibility
- FieldLabel is bound to the control automatically; no htmlFor or id is needed.
- FieldDescription and a visible FieldError are linked to the control with aria-describedby.
- A failed check sets aria-invalid on the control, which also turns a rendered Input or Textarea border red.
- FieldGroup renders a <fieldset> whose legend names the group; its description is linked with aria-describedby.
- The error message eases in with a 2px rise and only fades under reduced motion.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/field.tsxfield- Also installs label@0.1.0registry dependency
- Also installs input@0.1.1registry dependency
- Also installs textarea@0.1.1registry dependency
- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/field/0.1.0.json.
ui/field.tsxShowHide
ui/field.tsx
"use client";
import { Field as BaseField } from "@base-ui/react/field";
import { Fieldset as BaseFieldset } from "@base-ui/react/fieldset";
import { type ReactNode, useId } from "react";
import { Label } from "./label";
type ClassName<State> = string | ((state: State) => string | undefined) | undefined;
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
/** Prepends base classes while keeping Base UI's state-function form of className working. */
function withBase<State>(base: string, className: ClassName<State>) {
return typeof className === "function" ? (state: State) => cx(base, className(state)) : cx(base, className);
}
/**
* Groups a label, a control, a description, and an error, and wires them together: the label
* names the control, the description and error describe it, and the control gets `aria-invalid`
* when validation fails. Pass `validate` and `validationMode` to validate on submit, blur, or change.
*/
export function Field({ className, ...props }: BaseField.Root.Props) {
return <BaseField.Root className={withBase("grid content-start gap-1.5", className)} {...props} />;
}
export interface FieldLabelProps extends BaseField.Label.Props {
/** Marks the field as required with a quiet asterisk. Set `required` on the control to enforce it. */
required?: boolean;
/** Adds an "Optional" note, for forms where most fields are required. */
optional?: boolean;
}
/** The field's label. Bound to the control automatically, so no `htmlFor` is needed. */
export function FieldLabel({ required, optional, ...props }: FieldLabelProps) {
return <BaseField.Label render={<Label required={required} optional={optional} />} {...props} />;
}
const controlBase = cx(
"h-9 w-full min-w-0 rounded-lg border border-zinc-300 bg-white px-3 text-sm text-zinc-900 shadow-sm placeholder:text-zinc-400",
"transition-[border-color,box-shadow] duration-150 motion-reduce:transition-none",
"focus-visible:border-sky-500 focus-visible:ring-3 focus-visible:ring-sky-500/20 focus-visible:outline-none",
"disabled:cursor-not-allowed disabled:bg-zinc-50 disabled:opacity-60",
"dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-100 dark:placeholder:text-zinc-500 dark:disabled:bg-zinc-900",
);
// Applied on top of a rendered Input or Textarea, whose own border only turns red through its `error` prop.
const invalidControl = cx(
"aria-invalid:border-red-400 aria-invalid:focus-visible:border-red-500 aria-invalid:focus-visible:ring-red-500/20",
"dark:aria-invalid:border-red-500/60",
);
/**
* The control to label and validate. Renders a text input styled like Input. To use the existing
* Input or Textarea, pass `render={<Input />}` or `render={<Textarea autoGrow />}`: they keep their
* own styles and pick up the field's id, label, description, and invalid state.
*/
export function FieldControl({ render, className, ...props }: BaseField.Control.Props) {
return (
<BaseField.Control
render={render}
className={withBase(render ? invalidControl : cx(controlBase, invalidControl), className)}
{...props}
/>
);
}
/** Helper text under the control, linked with `aria-describedby`. */
export function FieldDescription({ className, ...props }: BaseField.Description.Props) {
return (
<BaseField.Description
className={withBase("text-sm leading-5 text-zinc-500 dark:text-zinc-400", className)}
{...props}
/>
);
}
/**
* The validation message. Shows when the control is invalid: by default for any failed check,
* or only for one with `match="valueMissing"` (any ValidityState key). Pass `match` as `true`
* to show it unconditionally, for errors that come from a server or a form library.
* It eases in with a 2px rise and leaves faster than it came.
*/
export function FieldError({ className, render, ...props }: BaseField.Error.Props) {
return (
<BaseField.Error
className={withBase(
cx(
"flex items-start gap-1.5 text-sm leading-5 text-red-600 dark:text-red-400",
"transition-[opacity,translate] duration-200 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none",
"data-[starting-style]:opacity-0 motion-safe:data-[starting-style]:-translate-y-0.5",
"data-[ending-style]:opacity-0 data-[ending-style]:duration-100 data-[ending-style]:ease-out",
),
className,
)}
// The render function wraps whichever message is shown: yours, or the browser's validation message.
render={
render ??
(({ children, ...rest }) => (
<div {...rest}>
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none" className="mt-0.5 size-4 shrink-0">
<circle cx="8" cy="8" r="6.25" stroke="currentColor" strokeWidth="1.5" />
<path d="M6 6l4 4M10 6l-4 4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
</svg>
<span className="min-w-0">{children}</span>
</div>
))
}
{...props}
/>
);
}
export interface FieldGroupProps extends Omit<BaseFieldset.Root.Props, "children"> {
/** Names the group. Rendered as the fieldset's legend. */
legend?: ReactNode;
/** A sentence under the legend about the whole group. */
description?: ReactNode;
children?: ReactNode;
}
/**
* A fieldset that names a set of related fields, such as an address or a notification section.
* `disabled` disables every field inside it. Fields stack with even spacing; pass a grid class
* in `className` to lay them out side by side.
*/
export function FieldGroup({ legend, description, className, children, ...props }: FieldGroupProps) {
const descriptionId = useId();
return (
<BaseFieldset.Root
aria-describedby={description != null ? descriptionId : undefined}
className={withBase("m-0 grid min-w-0 gap-5 border-0 p-0", className)}
{...props}
>
{legend != null || description != null ? (
<div className="col-span-full grid gap-1">
{legend != null ? (
<BaseFieldset.Legend className="text-sm leading-5 font-semibold text-zinc-950 dark:text-white">
{legend}
</BaseFieldset.Legend>
) : null}
{description != null ? (
<p id={descriptionId} className="text-sm leading-5 text-zinc-500 dark:text-zinc-400">
{description}
</p>
) : null}
</div>
) : null}
{children}
</BaseFieldset.Root>
);
}
/** A hairline between field groups inside one form. */
export function FieldSeparator({ className }: { className?: string }) {
return <hr className={cx("m-0 h-px border-0 bg-zinc-950/[0.07] dark:bg-white/[0.08]", className)} />;
}