Field
Groups a label, a control, and hints, and wires their ids and ARIA for you.
The parts read the control id, disabled, required, and state from the field.
Label points for at the control. Each Hint joins the control’s aria-describedby.
RadioGroup takes aria-labelledby from the labels.
Field.StateIcon shows the state. A prop passed to a part directly
still wins.
An error state sets aria-invalid on the control and changes its color. Color is never
the only signal, so pair it with a Hint that says what is wrong, or with
Field.StateIcon.
<Field class="flex flex-col gap-1" required state="error"> <Label>Email</Label> <Input type="email" bind:value /> <Hint>We'll never share it.</Hint> <Hint>Enter a valid address.</Hint></Field>Lowercase letters, numbers, and dashes.
<Field
required={false}
disabled={false}
state="none"
/>- Generates the control’s id (
controlId) and hands it to the label’sforand the control. - Collects every
Hintinto the control’saria-describedby, and names aRadioGroupfrom the label. disabled,required, andstateset once here reach every part.- A prop passed to a part directly always wins over the field’s value.
Anatomy
Section titled “Anatomy”A field is a plain <div> around one control, with any number of labels and hints in any order. Its one part is Field.StateIcon, which shows the field’s state as an icon.
<Field> <Label /> <Input /> <!-- or NumberInput, Checkbox, RadioGroup, Select --> <Hint /></Field>
<Field> <Label /> <Input.Group> <Input /> <Field.StateIcon /> </Input.Group> <Hint /></Field>A labeled input with a hint
Section titled “A labeled input with a hint”Nothing in this example names an id, yet the label, the input, and the hint are associated.
Lowercase letters, numbers, and dashes.
Code
<script lang="ts"> import { Field, Hint, Input, Label } from "@viamrobotics/prime-ui";
let name = $state("");</script>
<Field class="not-content flex max-w-xs flex-col gap-1" required> <Label>Machine name</Label> <Input bind:value={name} placeholder="rover-1" /> <Hint>Lowercase letters, numbers, and dashes.</Hint></Field>A state icon inside the input
Section titled “A state icon inside the input”Field.StateIcon reads the field’s state and renders nothing for none. Place it after the input inside an Input.Group to put the icon inside the border.
Spaces and capitals are not allowed.
Code
<script lang="ts"> import { Field, Hint, Input, Label } from "@viamrobotics/prime-ui";
let name = $state("Rover 1");</script>
<Field class="not-content flex max-w-xs flex-col gap-1" state="error"> <Label>Machine name</Label> <Input.Group> <Input bind:value={name} /> <Field.StateIcon /> </Input.Group> <Hint>Spaces and capitals are not allowed.</Hint></Field>Every control
Section titled “Every control”Input: required, error, disabled
Lowercase letters, numbers, and dashes.
Lowercase letters, numbers, and dashes.
Spaces and capitals are not allowed.
Unavailable while the part is offline.
Select
Applies to every new part.
RadioGroup, named by the label
The label reaches the group through aria-labelledby.
Checkbox
Required before the part can be deployed.
What the parts take from the field
Section titled “What the parts take from the field”| Part | Reads from Field |
|---|---|
Label |
for (the control id), required, disabled |
Hint |
disabled, state (error turns red, warn and info are colored too), and joins the control’s aria-describedby |
Input, NumberInput |
controlId, disabled, required, state, aria-describedby |
Checkbox |
controlId, disabled, required, state, aria-describedby |
RadioGroup |
controlId, disabled, required, state, aria-labelledby, aria-describedby |
Select / Select.Trigger |
disabled and required on the root, and controlId, state, and aria-describedby on the trigger |
Field.StateIcon |
state, and renders nothing for none |
A Hint in an error field is described by the control, not announced. To have a screen reader read an error the moment it appears, pass role="alert" to that Hint. It goes straight to the <p>.
Without a field
Section titled “Without a field”Every part still works on its own. Wire it by hand with for, id, and aria-describedby:
<Label for="email" required>Email</Label><Input id="email" aria-describedby="email-hint" required /><Hint id="email-hint">We'll never share it.</Hint>Styling
Section titled “Styling”Field renders a bare <div> and takes no layout stance, so pass class to stack or inline its parts. controlId is the id the field assigns to the control. Pass your own to point an external <label for> or a test selector at it. A plain id lands on the wrapper <div>.
| Prop | Type | Default | Description |
|---|---|---|---|
controlId | string | Id the field assigns to the control inside. Generated when omitted. id lands on this wrapper. | |
disabled | boolean | false | Disable the control and dim the label and hints. |
required | boolean | false | Mark the control required and show the asterisk on the label. |
state | FieldState | 'none' | Contextual state shared with the control and hints. |
children | Snippet<[FieldContext]> | The parts. Receives the field context, with controlId, disabled, required, and state. |
Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'children'>, spread onto the element.
Field.StateIcon
Shows the icon for a Field’s state, or for its own state prop outside a field. Renders
nothing for none. Place it after the input inside an Input.Group, or anywhere in the
field.
<Field state="error"> <Label>Email</Label> <Input.Group> <Input type="email" bind:value /> <Field.StateIcon /> </Input.Group></Field>Takes extraClasses, ...restProps }: Props as its props.