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
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.
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.
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.
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.
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.
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.
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
Shared props
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.