Skip to content
Shaken UI
Sign in

Field

Save

A 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
Agent

How this agent appears in runs and approval requests.

Shown in run logs and in the approval inbox.

0 of 400 characters used.


Limits

Installation

npx @shakenui/cli add field

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add field --dry-run

Usage

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

PropTypeDefaultDescription
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.
invalidboolean—Field: forces the invalid state, for errors from a server or a form library.
disabledbooleanfalseField or FieldGroup: disables the control(s) inside.
required / optionalbooleanfalseFieldLabel: adds a required asterisk or an Optional note.
renderReactElement—FieldControl: render the existing Input or Textarea, e.g. render={<Input />}. Without it, a text input styled like Input is rendered.
matchboolean | keyof ValidityState—FieldError: show only for one validity check, or always with true.
legend / descriptionReactNode—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.tsxShow
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)} />;
}