Field
Field wraps one control with a label, an optional note and a hint line. You pass the control as component;
Field injects value, onChange, variant, readOnly and reset into it. Every key of a
Form renders as a Field.Forms
When to use
Use when
- A control needs a label, a hint or a validation message in the design-system layout.
- You build a form without
Formbut want the same field anatomy.
Avoid when
- Inside a
Form— declare the field infieldsinstead of renderingFieldyourself. - Label and control need a custom arrangement (side by side, a complex grid) — compose the parts directly.
Usage
What should we call you?
Optional
We will use it to send you updates.Password must be at least 8 characters long.
Passwords match.
<Field component={Input} name="name" label="Name" hintText="What should we call you?" />
<Field component={Input} name="email" label="Email" optionalText="Optional" />
<Field component={Input} name="password" label="Password" error hintErrorText="At least 8 characters." />
<Field component={Input} name="confirm" label="Confirmation" success hintSuccessText="Passwords match." />error and success paint the label, the hint and the control; variant sets the state directly and wins over both.
The hint line always reserves one line, so switching to an error does not shift the content below. readOnly prints
readOnlyText (default apenas leitura) in the note slot.
Rich hints
hintText, hintErrorText and hintSuccessText accept a ReactNode, so a hint can carry an inline action:
<Field
component={Input}
name="amount"
label="Amount"
hintText={
<Flex flexDirection="row" justifyContent="between" width="100%">
<Text text="Daily limit: 5,000" />
<Button variant="linked" size="extraSmall" text="Use all" onClick={fillMax} />
</Flex>
}
/>Fill
With a TextArea, inputProps={{ fill: true }} makes the whole field grow into the leftover space
of its flex parent; the label and hint keep their height and only the control grows.
<Flex height="100dvh">
<Field component={TextArea} name="content" label="Content" inputProps={{ fill: true, rows: 4 }} />
</Flex>Accessibility
- The label is a native
<label for={name}>and the control receivesid={name}: always passname. hideLabelkeeps the label as the control's name but takes it out of the layout, so the control lines up with a bare control under a shared heading.- Controls a
<label>cannot name (markedariaLabelledByField, such asInputRange) getaria-labelledbypointing at the label. Anaria-labeloraria-labelledbyininputPropswins. - While the field has an error (
errorsorerror), the control getsaria-invalid; a visual-onlyvariant="error"does not set it.aria-describedbypoints at the visible hint.
Properties
Name
Type
Default
Description
component *anynoneerrorbooleannoneerrorsanynonefieldPropsDefaultFlexInterfacenonehideLabelbooleanfalseHides the label visually but keeps it as the control's accessible name.
The label row takes no space (no height, no gap), so the control lines
up with a bare control beside it.
hintErrorTextReactNode'Something went wrong'Fallback message displayed in error. Inside `Form`, the validation
message (`errors.message`, e.g. the Zod schema's text) is shown when
present; `hintErrorText` covers errors without one.
hintSuccessTextReactNodenoneMessage displayed when `success`. Accepts `ReactNode`.
hintTextReactNodenoneNeutral message below the input. Accepts `ReactNode` (not just `string`):
besides text, it can carry inline actions (e.g. a "use all" button) or a
supporting `Text` (e.g. a daily limit) — previously these affixes had to
be rendered as siblings outside the `Field`. Backward-compatible widening
(`string ⊂ ReactNode`).
inputPropsanynoneProps forwarded to `component`. `inputProps.fill === true` (`TextArea`)
also makes the field join its flex parent's layout, so the control can
fill the leftover space while the label and hint keep their own height.
labelstringnonenamestringnoneoptionalTextstringnonereadOnlybooleannonereadOnlyTextstringnonesetFieldValueUseFormSetValue<any>nonesuccessbooleannonevalueanynonevariant"default""success""error"nonePlacement props (area, alignSelf, justifySelf) apply to the field; fieldProps reaches its inner Flex.