Skip to content
Browse documentation
whisk/ui

Field

Compose a label, control, help text, and validation message.

Overview

Field composes one Whisk/UI control with a label, supporting text, validation feedback, and shared control state. It provides the relationships; your application owns the value and validation decision.

See Supported controls for automatic wiring and the manual pattern for other controls.

Use when

A form control needs a visible label, help text, error message, or shared field state.

Use instead

Use Label with a single control when no description or validation message is needed.

Usage

Shown to workspace members.
import { Field, TextInput } from "@smoothie-framework/whisk-react";

<Field label="Project name" description="Shown to workspace members.">
  <TextInput placeholder="Atlas" />
</Field>

Examples

Validation

The application decides when to validate. Submitting an empty value shows the error; entering a value clears it. Use onInput so controlled typing updates in both React and Octane.

import { useState } from "react";
import { Box, Button, Field, Stack, TextInput } from "@smoothie-framework/whisk-react";

export function ProjectNameForm() {
  const [name, setName] = useState("");
  const [submitted, setSubmitted] = useState(false);
  const error = submitted && name.trim() === "" ? "Enter a project name." : undefined;

  return (
    <Box
      as="form"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(true);
      }}
    >
      <Stack gap={3}>
        <Field label="Project name" error={error}>
          <TextInput
            value={name}
            onInput={(event) => {
              setName(event.currentTarget.value);
              if (event.currentTarget.value.trim() !== "") setSubmitted(false);
            }}
          />
        </Field>
        <Button type="submit">Save project</Button>
      </Stack>
    </Box>
  );
}

Error text

Pass the error only after application validation has found a problem. A nonempty error marks the nested Whisk/UI control invalid and connects the feedback automatically.

Enter a complete email address.
import { Field, TextInput } from "@smoothie-framework/whisk-react";

<Field
  controlId="workspace-email"
  label="Workspace email"
  error="Enter a complete email address."
>
  <TextInput type="email" defaultValue="team@" />
</Field>

Forms

Use react-hook-form for registration and validation. register works because Whisk/UI controls forward their ref; pass its error message to Field. No TanStack Form integration is currently provided.

import { useForm } from "react-hook-form";
import { Box, Button, Field, Stack, TextInput } from "@smoothie-framework/whisk-react";

type ProjectValues = { name: string };

function onSubmit(values: ProjectValues) {
  // Send values to your application.
}

export function ProjectForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<ProjectValues>();
  const name = register("name", { required: "Enter a project name." });

  return (
    <Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
      <Stack gap={3}>
        <Field label="Project name" required error={errors.name?.message}>
          <TextInput required {...name} />
        </Field>
        <Button type="submit">Save project</Button>
      </Stack>
    </Box>
  );
}

Description

Pair a Textarea with a description when readers need guidance that does not belong in the label or placeholder.

Summarize the changes people will see.
import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field
  label="Release notes"
  description="Summarize the changes people will see."
>
  <Textarea rows={4} />
</Field>

Horizontal

Use horizontal orientation when a short label and its control need to share one row.

import { Field, TextInput } from "@smoothie-framework/whisk-react";

<Field label="Port" orientation="horizontal">
  <TextInput inputMode="numeric" defaultValue="3000" />
</Field>

Choice label

A Switch owns its label. Omit Field label when the choice label should appear after the control.

Sent to your email.
import { Field, Switch } from "@smoothie-framework/whisk-react";

<Field orientation="horizontal" description="Sent to your email.">
  <Switch label="Notify me when deployment finishes" />
</Field>

Disabled

Set disabled on Field to share the unavailable state with its nested Whisk/UI control.

import { Field, TextInput } from "@smoothie-framework/whisk-react";

<Field label="Workspace name" disabled>
  <TextInput defaultValue="Atlas" />
</Field>

Required

Set required when the control must have a value before the form can be submitted. The label shows a required marker by default.

import { Field, TextInput } from "@smoothie-framework/whisk-react";

<Field label="Project name" required>
  <TextInput />
</Field>

Optional

Use the optional indicator only when that distinction helps people complete the form.

import { Field, TextInput } from "@smoothie-framework/whisk-react";

<Field
  label="Billing reference"
  indicator="optional"
  optionalText="Optional"
>
  <TextInput placeholder="PO number" />
</Field>

Fieldset

Use FieldSet when several independently labelled controls share a group name and guidance. Do not put FieldSet inside a single-control Field.

Contact details
Used only for account recovery.
import { Field, FieldGroup, FieldSet, TextInput } from "@smoothie-framework/whisk-react";

<FieldSet
  legend="Contact details"
  description="Used only for account recovery."
>
  <FieldGroup>
    <Field label="Email address" required>
      <TextInput type="email" autoComplete="email" />
    </Field>
    <Field label="Phone number">
      <TextInput type="tel" autoComplete="tel" />
    </Field>
  </FieldGroup>
</FieldSet>

Field group

Use FieldGroup only for layout. Each nested Field keeps its own label, description, error, and control identity.

import { Field, FieldGroup, TextInput } from "@smoothie-framework/whisk-react";

<FieldGroup>
  <Field label="First name" required>
    <TextInput autoComplete="given-name" />
  </Field>
  <Field label="Last name" required>
    <TextInput autoComplete="family-name" />
  </Field>
</FieldGroup>

ID

Field creates the control ID by default. If the application needs a known ID, set it on controlId and use the same value on the nested Whisk/UI control.

import { Field, TextInput } from "@smoothie-framework/whisk-react";

<Field controlId="known-project-slug" label="Project slug">
  <TextInput id="known-project-slug" defaultValue="atlas" />
</Field>

Supported controls

Field automatically connects only the Whisk/UI controls listed below; every other control needs explicit wiring.

ControlInside FieldNotes
TextInputYesReceives the Field control ID, label, description, error, invalid, required, disabled, and read-only state.
TextareaYesReceives the Field control ID, label, description, error, invalid, required, disabled, and read-only state.
SelectYesReceives the Field control ID, label, description, error, invalid, required, disabled, and read-only state.
CheckboxYesReceives the Field control ID and shared state; it can also render its own choice label after the control.
SwitchYesReceives the Field control ID and shared state; it can also render its own choice label after the control.
ComboboxYesReceives the Field control ID, relationships, and shared state; the application still owns its selected value.
RadioYesReceives the Field control ID and shared state. Use it only as one standalone radio, not as a choice group.
ComposerRoot with ComposerInputYesComposerInput receives Field relationships through its Textarea; Field shares disabled and read-only state, while the application owns the draft and submission.
InputGroup with TextInputYesInputGroup frames exactly one TextInput; the nested control receives the Field wiring.
RadioGroup or CheckboxGroupNoEach group owns its own label, description, error, and group semantics. Do not nest it in Field; use FieldSet for several independently labelled controls.
Native input, textarea, or selectNoUse TextInput, Textarea, or Select instead; Field does not wire native controls.
Third-party controlManualField does not inspect or modify third-party controls. Pass the required ID, ARIA attributes, and state to that control yourself.

Third-party controls

Third-party controls are not rendered in the docs, so this source-only example shows the required wiring. Field generates {id}-label, {id}-description, and {id}-error.

tsx
import { DatePicker } from "@acme/date-picker";
import { Field } from "@smoothie-framework/whisk-react";

const error = validationErrors.startDate; // from your validation state

<Field
  id="start-date"
  controlId="start-date-input"
  label="Start date"
  description="Choose the first day of the project."
  error={error}
>
  <DatePicker
    id="start-date-input"
    required
    aria-labelledby="start-date-label"
    aria-describedby={error ? "start-date-description start-date-error" : "start-date-description"}
    aria-errormessage={error ? "start-date-error" : undefined}
    aria-invalid={Boolean(error)}
  />
</Field>

Props

Component props

PropTypeDefaultDescription
id | controlIdstringnoneSet a stable field base ID or the owned control ID. Usually omit both; if the nested Whisk/UI control has an id, it must equal controlId.
labelReactNodenoneRender the visible label and connect it to the one owned control.
descriptionReactNodenoneAdd supporting information that the control references.
errorReactNodenoneShow validation feedback. A nonempty error makes the Field invalid unless invalid is set explicitly.
invalidbooleannoneOverride the invalid state inferred from error. Use invalid={false} only when application state retains an error but its feedback must stay hidden; otherwise omit it.
required | disabled | readOnlybooleanfalseShare native required, disabled, or read-only state with the nested Whisk/UI control.
orientationvertical | horizontalverticalArrange the label and field body vertically or side by side.
indicatorrequired | optional | nonerequiredShow a required marker when required is true, optional text when required is false, or neither.
optionalTextstring(Optional)Set the text shown when indicator is optional and required is false.

Shared props

PropSupportedNotes
as / asChildNoField owns its div, label, messages, and one control relationship.
Style propsNoField exposes semantic form props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the Field wrapper.
refYesForwards to the Field wrapper.
Native HTML attributesYesNative div attributes are forwarded to the Field wrapper.

Accessibility

Field connects its label, description, and visible error to one nested Whisk/UI control, and errors announce politely when they appear. The required asterisk is aria-hidden; supported Whisk/UI controls receive native required. Keep one control per Field, even when application layout wraps it. Use FieldSet for several independently labelled controls, and do not wrap RadioGroup or CheckboxGroup in Field because they already own their group semantics and relationships.

Content guidance

Use a noun phrase for the label. Add a description only when it adds information, make an error say what needs attention and what to do next, and mark fields required or optional, not both.

PropDoDon't
labelProject nameEnter project name:
descriptionShown to workspace members.Enter a name.
errorEnter a project name.Invalid input.