Search docs

Forms

Label, describe and validate form controls with Field and Fieldset, and submit them with native forms.

Field#

Field connects a form control with its label, description and error message. Put the parts and a control inside Field.Root:

<Field.Root invalid={username.value.trim() === ''} required>
  <Field.Label>Username</Field.Label>
  <Field.Input bind:value={username} />
  <Field.ErrorMessage>Username is required.</Field.ErrorMessage>
</Field.Root>
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Field } from '@leve-ui/field';
import styles from './invalid.css?inline';

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

  const value = useSignal('leve');

  return (
    <Field.Root invalid={value.value.trim() === ''} required class="field-invalid">
      <Field.Label class="field-invalid-label">Username</Field.Label>
      <Field.Input bind:value={value} class="field-invalid-input" />
      <Field.ErrorMessage class="field-invalid-error-message">
        Username is required.
      </Field.ErrorMessage>
    </Field.Root>
  );
});

Field.Input and Field.Textarea render native <input> and <textarea> elements. Checkbox and Switch join a Field the same way.

What the Field sets on the control#

Field.Root is the single source of truth for the field. The control reads it and renders the attributes itself:

Field.Root propOn the control
(generated ids)id, so that Field.Label points at the control
hasDescriptionaria-describedby references Field.Description
invalidaria-invalid="true" and data-invalid; aria-describedby references Field.ErrorMessage
disableddisabled and data-disabled
requiredrequired on native elements, aria-required on Checkbox and Switch

The Root also exposes data-invalid, data-disabled and data-required for styling.

A few rules follow from this, because Qwik renders the parts on the server in document order and the control is rendered before the parts that come after it:

  • Set hasDescription when you render Field.Description. Without it, the control is not described by it.
  • Render Field.ErrorMessage only while the field is invalid. The control references it only then.
  • Override ids on the Root. Inside a Field, the control's own id is not used. Pass ids to Field.Root instead, for example ids={{ control: 'email' }}.
  • States are combined. disabled and required set on a control apply together with the ones on the Field, and the ids you pass in aria-describedby are kept.

Every control also works without a Field. Outside a Field, it uses its own id (or a generated one) and its own disabled and required props.

With a Checkbox or Switch#

For controls with several parts, the Field wires the interactive part (Checkbox.Control, Switch.Control), so Field.Label names it:

<Field.Root hasDescription>
  <Checkbox.Root>
    <Checkbox.Control>
      <Checkbox.Indicator>
        <LuCheck aria-hidden="true" />
      </Checkbox.Indicator>
    </Checkbox.Control>
  </Checkbox.Root>
  <Field.Label>Remember me</Field.Label>
  <Field.Description>Save your session on this device for 30 days.</Field.Description>
</Field.Root>
Save your session on this device for 30 days.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { Field } from '@leve-ui/field';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './with-field.css?inline';

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

  return (
    <Field.Root hasDescription class="checkbox-with-field-field">
      <div class="checkbox-with-field-row">
        <Checkbox.Root class="checkbox-with-field-root">
          <Checkbox.Control class="checkbox-with-field-control">
            <Checkbox.Indicator class="checkbox-with-field-indicator">
              <LuCheck class="checkbox-with-field-icon" aria-hidden="true" />
            </Checkbox.Indicator>
          </Checkbox.Control>
          <Checkbox.HiddenInput />
        </Checkbox.Root>
        <Field.Label class="checkbox-with-field-label">Remember me</Field.Label>
      </div>
      <Field.Description class="checkbox-with-field-description">
        Save your session on this device for 30 days.
      </Field.Description>
    </Field.Root>
  );
});

Fieldset#

Fieldset groups related controls under one label. It renders a native <fieldset> and <legend>, so the group is named by its Legend. disabled on Fieldset.Root disables every form control inside it, both native and leve-ui controls, and both parts expose data-disabled.

<Fieldset.Root>
  <Fieldset.Legend>Shipping method</Fieldset.Legend>
  <label>
    <input type="radio" name="shipping" value="standard" /> Standard
  </label>
  <label>
    <input type="radio" name="shipping" value="express" /> Express
  </label>
</Fieldset.Root>
Shipping method
import { component$, useStyles$ } from '@builder.io/qwik';
import { Fieldset } from '@leve-ui/fieldset';
import styles from './default.css?inline';

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

  return (
    <Fieldset.Root class="fieldset-default">
      <Fieldset.Legend class="fieldset-default-legend">Shipping method</Fieldset.Legend>
      <label class="fieldset-default-option">
        <input class="fieldset-default-radio" type="radio" name="shipping" value="standard" />{' '}
        Standard
      </label>
      <label class="fieldset-default-option">
        <input class="fieldset-default-radio" type="radio" name="shipping" value="express" />{' '}
        Express
      </label>
    </Fieldset.Root>
  );
});

Native form submission#

Switch, Checkbox and Radio Group are built from a <button> (or elements with a role) so that you can style their inner parts. These elements do not take part in native forms by themselves. Add the HiddenInput part to include the value in form submissions and FormData:

<form preventdefault:submit onSubmit$={(_, form) => console.log(new FormData(form))}>
  <Switch.Root>
    <Switch.Label>Notifications</Switch.Label>
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    <Switch.HiddenInput name="notifications" />
  </Switch.Root>
  <button type="submit">Save</button>
</form>
import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Switch } from '@leve-ui/switch';
import styles from './form.css?inline';

export default component$(() => {
  useStyles$(styles);
  const submittedData = useSignal('');

  const handleSubmit$ = $((_event: unknown, form: HTMLFormElement) => {
    const formData = new FormData(form);
    submittedData.value = JSON.stringify(Object.fromEntries(formData));
  });

  return (
    <form class="switch-form-form" preventdefault:submit onSubmit$={handleSubmit$}>
      <Switch.Root class="switch-form-root">
        <Switch.Label class="switch-form-label">Notifications</Switch.Label>
        <Switch.Control class="switch-form-control">
          <Switch.Thumb class="switch-form-thumb" />
        </Switch.Control>
        <Switch.HiddenInput name="notifications" />
      </Switch.Root>
      <button type="submit" class="switch-form-submit">
        Save
      </button>
      <output class="switch-form-output">{submittedData.value}</output>
    </form>
  );
});
  • Pass name, value and form to HiddenInput like you would to an <input>. The library sets checked, required and disabled from the state of the component.
  • The hidden input is hidden from assistive technologies and is not in the tab order. It is hidden visually with an inline position: absolute style instead of the hidden attribute, so that native required validation still works. Set position: relative on the Root so that it stays in place.
  • HiddenInput is optional. Without it, the control works the same but does not submit a value.

Radio Group submits the value of the selected item:

Subscription billing
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { RadioGroup } from '@leve-ui/radio-group';
import styles from './with-form.css?inline';

export default component$(() => {
  useStyles$(styles);
  const submittedValue = useSignal<string | null>(null);

  return (
    <div class="radio-group-with-form-wrapper">
      <form
        class="radio-group-with-form-form"
        preventdefault:submit
        onSubmit$={(event) => {
          const form = event.target as HTMLFormElement;
          const formData = new FormData(form);
          submittedValue.value = (formData.get('subscription') as string) || '(none)';
        }}
      >
        <RadioGroup.Root defaultValue="monthly" class="radio-group-with-form-root">
          <RadioGroup.Label class="radio-group-with-form-label">
            Subscription billing
          </RadioGroup.Label>
          <RadioGroup.Item value="monthly" class="radio-group-with-form-item">
            <RadioGroup.Indicator class="radio-group-with-form-indicator" />
            Monthly billing ($10/mo)
          </RadioGroup.Item>
          <RadioGroup.Item value="yearly" class="radio-group-with-form-item">
            <RadioGroup.Indicator class="radio-group-with-form-indicator" />
            Yearly billing ($100/yr)
          </RadioGroup.Item>
          <RadioGroup.HiddenInput name="subscription" />
        </RadioGroup.Root>
        <button type="submit" class="radio-group-with-form-form-button">
          Submit
        </button>
      </form>
      {submittedValue.value !== null && (
        <p class="radio-group-with-form-submitted" data-testid="submitted-value">
          Submitted: {submittedValue.value}
        </p>
      )}
    </div>
  );
});

Next steps#