Search docs

Field

Connects a label, description and error message to a form control.

There is no WAI-ARIA APG pattern for form fields. Field uses the native <label>, <input> and <textarea> elements, and connects them with for, aria-describedby and aria-invalid.

We'll never share your email.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Field } from '@leve-ui/field';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Field.Root hasDescription class="field-default">
      <Field.Label class="field-default-label">Email</Field.Label>
      <Field.Input type="email" placeholder="[email protected]" class="field-default-input" />
      <Field.Description class="field-default-description">
        We'll never share your email.
      </Field.Description>
    </Field.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/field

Anatomy#

import { Field } from '@leve-ui/field'; // or '@leve-ui/core'

<Field.Root>
  <Field.Label />
  <Field.Input /> {/* or <Field.Textarea /> */}
  <Field.Description />
  <Field.ErrorMessage />
</Field.Root>
PartElementDescription
Field.Root<div>Wraps the parts and holds the IDs and the invalid / disabled / required states.
Field.Label<label>The label of the control.
Field.Input<input>A single-line control.
Field.Textarea<textarea>A multi-line control.
Field.Description<div>A hint for the control.
Field.ErrorMessage<div>The error message. Rendered only while the Root is invalid.

Other leve-ui form controls, such as Checkbox, also read the Field and can be used instead of Field.Input.

Examples#

Invalid#

invalid on the Root shows Field.ErrorMessage and marks the input as invalid. In this demo, clear the input to see the error.

Disabled#

disabled on the Root disables the input.

Required#

required on the Root makes the input required.

Textarea#

Use Field.Textarea for multi-line text.

Tell us about yourself.

API Reference#

Root#

PropDefaultType
ids–{ control?: string; label?: string; description?: string; errorMessage?: string }

Overrides the element IDs of the parts. IDs can only be overridden here (adr/0024).

invalidfalseboolean

Marks the control as invalid (aria-invalid) and shows the ErrorMessage.

disabledfalseboolean

Disables the control.

requiredfalseboolean

Marks the control as required.

hasDescriptionfalseboolean

Set to true when a Field.Description is rendered, so that the control is described by it (aria-describedby).

Also accepts all <div> attributes.

Data attributeValue
data-leve-fieldAlways present
data-invalidPresent when invalid
data-disabledPresent when disabled
data-requiredPresent when required

IDs of the parts can only be overridden with ids on the Root; id on the parts is ignored inside a Field. Set hasDescription when you render a Field.Description, so that the control is described by it (ADR 0024).

Label#

No props of its own. Accepts all <label> attributes.

Data attributeValue
data-leve-field-labelAlways present
data-invalidPresent when the Field is invalid
data-disabledPresent when the Field is disabled
data-requiredPresent when the Field is required

Inside a Field, for points to the control.

Input#

PropDefaultType
bind:value–Signal<string>

A signal synced two-way with the input value.

invalidfalseboolean

Marks the control as invalid (aria-invalid="true", data-invalid). Inside a Field, the control is also invalid while the Field is.

bind:checked–Signal<boolean>

A signal synced two-way with the checked state (for checkbox and radio inputs).

Also accepts all <input> attributes.

Data attributeValue
data-leve-field-inputAlways present
data-invalidPresent when invalid
data-disabledPresent when disabled
data-requiredPresent when required

The input gets disabled and required from the Field. It also works outside a Field as a plain <input>; pass invalid to mark it as invalid there.

Textarea#

PropDefaultType
bind:value–Signal<string>

A signal synced two-way with the textarea value.

invalidfalseboolean

Marks the control as invalid (aria-invalid="true", data-invalid). Inside a Field, the control is also invalid while the Field is.

Also accepts all <textarea> attributes.

Data attributeValue
data-leve-field-textareaAlways present
data-invalidPresent when invalid
data-disabledPresent when disabled
data-requiredPresent when required

The textarea gets disabled and required from the Field. It also works outside a Field as a plain <textarea>; pass invalid to mark it as invalid there.

Description#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-field-descriptionAlways present
data-invalidPresent when the Field is invalid
data-disabledPresent when the Field is disabled
data-requiredPresent when the Field is required

ErrorMessage#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-field-error-messageAlways present
data-invalidPresent when the Field is invalid
data-disabledPresent when the Field is disabled
data-requiredPresent when the Field is required

Inside a Field, the error message is not rendered while the Field is not invalid.

Accessibility#

  • Field.Label is a native <label> whose for points to the control, so it names the control and clicking it focuses the control.
  • The control renders aria-describedby pointing to Field.Description (when hasDescription is set) and to Field.ErrorMessage (while invalid), after any aria-describedby you pass.
  • The control renders aria-invalid="true" while invalid, and the native disabled and required attributes.
  • Field.ErrorMessage renders role="alert", so screen readers announce the error when it appears. Pass role="status" to announce it without interrupting.
  • A disabled control is skipped by Tab.
  • Field has no keyboard interaction of its own.