Field

A field connects a form control to its label, its description and the errors it shows, and wires up id, for and aria-describedby for you.

<script setup lang="ts">
import { Field, FieldDescription, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
</script>

<template>
  <div data-slot="stack">
    <Field>
      <FieldLabel>Username</FieldLabel>
      <Input name="username" placeholder="hollis" autocomplete="username" />
      <FieldDescription
        >Choose a unique username for your account.</FieldDescription
      >
    </Field>
  </div>
</template>

Installation

npm install @ui-sdk/vue @ui-sdk/core

Composition

Use the following composition to build a Field:

Field
├── FieldLabel
├── Input
├── FieldDescription
└── FieldError

Usage

<script setup lang="ts">
import {
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
} from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
</script>

<template>
  <Field name="username">
    <FieldLabel>Username</FieldLabel>
    <Input autocomplete="username" required />
    <FieldDescription>This is your public name.</FieldDescription>
    <FieldError />
  </Field>
</template>

The control is one of ours, like an Input, a Textarea, a Select or a Checkbox, and it wires itself to the field.

The label names the control, and the description and any error that shows describe it.

Group related fields in a field set:

<FieldSet>
  <FieldLegend />
  <FieldDescription />
  <FieldGroup>
    <Field />
    <Field />
  </FieldGroup>
</FieldSet>

Controls

Use an Input for a line of text and a Textarea for more:

<Field>
  <FieldLabel>Feedback</FieldLabel>
  <Textarea name="feedback" />
</Field>

For a control we don't ship, like a native <select>, use FieldControl. It renders an <input>, or another element with the render slot, and connects it to the field the same way. An agent sees only our components, so it can't fill a FieldControl: use ours where there is one.

<Field>
  <FieldLabel>Department</FieldLabel>
  <FieldControl name="department">
    <template #render="{ props }">
      <select v-bind="props">
        <option value="design">Design</option>
        <option value="engineering">Engineering</option>
      </select>
    </template>
  </FieldControl>
</Field>

A Checkbox, Switch or Radio Group inside a field uses the field's label and description. Pressing the label toggles a checkbox or switch. A radio group takes the field's label as its name, and each radio keeps a label of its own:

<Field>
  <Switch name="mfa" />
  <FieldLabel>Two-factor authentication</FieldLabel>
  <FieldDescription>Ask for a code when you sign in.</FieldDescription>
</Field>

<Field>
  <FieldLabel>Plan</FieldLabel>
  <RadioGroup name="plan" default-value="monthly">
    <label>
      <Radio value="monthly" />
      Monthly
    </label>
    <label>
      <Radio value="yearly" />
      Yearly
    </label>
  </RadioGroup>
</Field>

Validation

Use native constraints such as required, type="email", and pattern. Errors appear after a submit attempt and update as the value changes. The first invalid control takes focus.

Leave an error empty to show the browser's message, or use match="valueMissing" and match="typeMismatch" for your own messages. Adding an error part replaces the browser's validation bubble with that message in the page.

<script setup lang="ts">
import {
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
} from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import { useLog } from "./log"

const log = useLog()

function submit(event: Event) {
  log(
    `Subscribed ${new FormData(event.currentTarget as HTMLFormElement).get("email")}`
  )
}
</script>

<template>
  <form data-slot="stack" @submit.prevent="submit">
    <Field name="email">
      <FieldLabel>Email</FieldLabel>
      <Input type="email" required placeholder="hollis@example.com" />
      <FieldDescription v-slot="{ state }">
        {{
          state.valid ? "Looks good." : "We'll send you a confirmation link."
        }}
      </FieldDescription>
      <FieldError match="valueMissing">Enter your email address.</FieldError>
      <FieldError match="typeMismatch"
        >Enter an email address like hollis@example.com.</FieldError
      >
    </Field>
    <Field name="website">
      <FieldLabel>Website</FieldLabel>
      <Input type="url" required placeholder="https://example.com" />
      <FieldError />
    </Field>
    <button type="submit" data-variant="solid">Subscribe</button>
  </form>
</template>

Errors from Your Code

Pass invalid when your server or form library supplies an error. true shows it immediately. Clear the value to return to the browser's validation.

Give this error its own text and set match to true. Named matches such as valueMissing still refer to native validation. :invalid="false" hides the field's invalid state, but does not make an invalid native control pass validation.

<Field name="email" :invalid="serverError ? true : undefined">
  <FieldLabel>Email</FieldLabel>
  <Input type="email" required @value-change="serverError = null" />
  <FieldError match="valueMissing">Enter your email address.</FieldError>
  <FieldError v-if="serverError" match>{{ serverError }}</FieldError>
</Field>

Required and Disabled

A required control marks every part with data-required, and the parts' state has required, so a label can show a mark with CSS alone.

A disabled field disables its control and marks every part with data-disabled, the way a disabled field set does for every field inside it.

Character Count

Keep the text in state and show its length in the description. Set maxlength on the control to enforce the limit.

<Field>
  <FieldLabel>Bio</FieldLabel>
  <Textarea v-model:value="bio" :maxlength="280" />
  <FieldDescription>{{ bio.length }} / 280</FieldDescription>
</Field>

Forms

The control submits its value under its own name, or the field's name if it has none. Reset restores the control's default and hides validation errors. Disabled controls are left out of the submitted values. See Forms for the shared form behavior.

Field Sets

A field set groups related fields under a legend, and disables them together.

<script setup lang="ts">
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
</script>

<template>
  <FieldSet>
    <FieldLegend>Address</FieldLegend>
    <FieldDescription
      >We need your address to deliver your order.</FieldDescription
    >
    <FieldGroup>
      <Field name="street">
        <FieldLabel>Street address</FieldLabel>
        <Input autocomplete="street-address" />
      </Field>
      <div data-slot="grid">
        <Field name="city">
          <FieldLabel>City</FieldLabel>
          <Input autocomplete="address-level2" />
        </Field>
        <Field name="postal-code">
          <FieldLabel>Postal code</FieldLabel>
          <Input autocomplete="postal-code" />
        </Field>
      </div>
    </FieldGroup>
  </FieldSet>
</template>

FieldSet is a native <fieldset> and FieldLegend a native <legend>, so the set is named, and disabled, before scripts run. Keep the legend the first child. A legend rendered as another element through its render slot, like a <div>, still names the set through aria-labelledby.

A FieldDescription right inside the set, outside any Field, describes the set, so screen readers read it as focus enters. FieldGroup is a <div> that stacks the fields, with no role and no state: the field set is what names and disables a group.

Disabled Field Sets

Disabling the set disables its controls and nested field sets. The form leaves their values out of submissions.

<FieldSet :disabled="sameAsShipping">
  <FieldLegend>Billing address</FieldLegend>
  <Field name="billing-street">
    <FieldLabel>Street address</FieldLabel>
    <Input autocomplete="billing street-address" />
  </Field>
</FieldSet>

Groups in a Field Set

The legend names a checkbox group or a radio group inside the set, so the group needs no label of its own.

<FieldSet>
  <FieldLegend>Notifications</FieldLegend>
  <CheckboxGroup name="notify" :default-value="['mentions']">
    <label>
      <Checkbox value="mentions" />
      Mentions
    </label>
    <label>
      <Checkbox value="follows" />
      New followers
    </label>
  </CheckboxGroup>
</FieldSet>

Custom Rendering

Every part takes a render slot, to render a different element or component in its place, like a <select> for FieldControl. It receives the props to bind and the field's state:

<FieldDescription>
  <template #render="{ props, state }">
    <p v-bind="props">{{ state.invalid ? "Use letters and numbers only." : "Letters and numbers." }}</p>
  </template>
</FieldDescription>

The default slot receives the state too, as v-slot="{ state }". FieldError's state also has the message for the current problem.

State is read lazily. A part re-renders for a change only if its render function or slot read that value. Each part's state is listed under State.

Custom Controls

useFieldControl lets a control of your own join the field around it, the way ours do. Outside a field it returns null. Inside one, it returns:

• name(): the field's name, for a control that doesn't set its own.
• disabled(): whether the field is disabled.
• props(props): the control's props with the field's merged in: the id, aria-labelledby, aria-describedby, aria-invalid, disabled and the field's data attributes, and a ref that tells the field which element is its control. The control keeps its own data-slot.

Call props while rendering, like in the template, so the control updates when the field changes, like when its label or errors appear.

<script setup lang="ts">
import { useAttrs } from "vue"
import { useFieldControl } from "@ui-sdk/vue/field"

defineOptions({ inheritAttrs: false })
const attrs = useAttrs()
const field = useFieldControl()
const input = () => ({
  type: "tel",
  autocomplete: "tel",
  name: field?.name(),
  ...attrs,
  "data-slot": "phone-input",
})
</script>

<template>
  <input v-bind="field ? field.props(input()) : input()" />
</template>

<Field>
  <FieldLabel>Phone</FieldLabel>
  <PhoneInput required />
  <FieldError />
</Field>

The field reads validity from the native inputs, selects and textareas inside it, so required and pattern work on the input above. A control that isn't a native input, like a row of buttons, takes part through a native input of its own: ours render one, visually hidden, beside the control.

To build a control from scratch on the primitives ours use, see Primitives.

Styling

Use data-invalid and data-valid for validation, and data-focused, data-required and data-disabled for the rest. Every part of a field gets the same attributes, so a label can turn red with its control.

Each part has a data-slot, such as field-label, and its state attributes are listed under Data Attributes.

Data Attributes

Field

[data-slot="field"]

FieldLabel

[data-slot="field-label"]

FieldControl

[data-slot="field-control"]

FieldDescription

[data-slot="field-description"]

FieldError

[data-slot="field-error"]

FieldSet

FieldGroup has data-slot="field-group" and no state attributes.

[data-slot="field-set"]

FieldLegend

[data-slot="field-legend"]

FieldDescription in a FieldSet

[data-slot="field-description"]

API Reference

Props are the same as below.

A field has no change events. Read its state from the parts' data attributes, or from render functions. Set debug to log every state change and its reason.

Field

FieldError

FieldSet

State

A FieldDescription receives the field's state, or only disabled when it describes a field set.

Every part of a field set receives the same state.

Accessibility

The label names the control with aria-labelledby, beside a native <label for> where the control can take one. The description and any error that shows describe it with aria-describedby, and an invalid control has aria-invalid. The tests below cover these connections and keyboard behavior.

In a field set:

In a form: