Skip to content

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’s for and the control.
  • Collects every Hint into the control’s aria-describedby, and names a RadioGroup from the label.
  • disabled, required, and state set once here reach every part.
  • A prop passed to a part directly always wins over the field’s value.

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>

Nothing in this example names an id, yet the label, the input, and the hint are associated.

Lowercase letters, numbers, and dashes.

Code
Basic.svelte
<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>

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
WithStateIcon.svelte
<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>

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.

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

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>

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

PropTypeDefaultDescription
controlIdstringId the field assigns to the control inside. Generated when omitted. id lands on this wrapper.
disabledbooleanfalseDisable the control and dim the label and hints.
requiredbooleanfalseMark the control required and show the asterisk on the label.
stateFieldState'none'Contextual state shared with the control and hints.
childrenSnippet<[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.