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-invalid {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
font-size: 14px;
}
.field-invalid-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.field-invalid-input {
height: 36px;
padding: 0 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font: inherit;
font-size: 14px;
}
.field-invalid-input::placeholder {
color: light-dark(#475569, #c9ddf0);
opacity: 0.7;
}
.field-invalid-input:focus-visible {
border-color: #009dfd;
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* Set by the library while the field is invalid */
.field-invalid-input[aria-invalid="true"] {
border-color: light-dark(#dc2626, #f87171);
}
.field-invalid-error-message {
margin: 0;
font-size: 13px;
color: light-dark(#dc2626, #f87171);
}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 prop | On the control |
|---|---|
| (generated ids) | id, so that Field.Label points at the control |
hasDescription | aria-describedby references Field.Description |
invalid | aria-invalid="true" and data-invalid; aria-describedby references Field.ErrorMessage |
disabled | disabled and data-disabled |
required | required 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
hasDescriptionwhen you renderField.Description. Without it, the control is not described by it. - Render
Field.ErrorMessageonly while the field is invalid. The control references it only then. - Override ids on the Root. Inside a Field, the control's own
idis not used. PassidstoField.Rootinstead, for exampleids={{ control: 'email' }}. - States are combined.
disabledandrequiredset on a control apply together with the ones on the Field, and the ids you pass inaria-describedbyare 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>
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>
);
});.checkbox-with-field-field {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
}
.checkbox-with-field-row {
display: flex;
align-items: center;
gap: 10px;
}
.checkbox-with-field-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-with-field-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-with-field-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-with-field-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-with-field-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-with-field-indicator {
display: none;
color: #ffffff;
}
.checkbox-with-field-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-with-field-icon {
width: 12px;
height: 12px;
}
.checkbox-with-field-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
/* Indented to line up with the label text (control 18px + gap 10px) */
.checkbox-with-field-description {
margin: 0;
padding-left: 28px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}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>
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>
);
});.fieldset-default {
display: flex;
flex-direction: column;
gap: 10px;
width: 280px;
margin: 0;
padding: 0;
border: none;
font-family: inherit;
}
.fieldset-default-legend {
padding: 0;
margin-bottom: 10px;
font-size: 14px;
font-weight: 600;
color: light-dark(#0f172a, #ffffff);
}
/* Each option is a selectable card */
.fieldset-default-option {
display: flex;
align-items: center;
gap: 10px;
padding: 10px 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.fieldset-default-option:has(input:checked) {
border-color: #009dfd;
background: light-dark(#daf0ff, #009dfd26);
}
.fieldset-default-radio {
width: 16px;
height: 16px;
margin: 0;
accent-color: #009dfd;
}
.fieldset-default-radio:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}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>
);
});.switch-form-form {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
}
.switch-form-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
justify-content: space-between;
gap: 12px;
min-width: 200px;
}
.switch-form-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.switch-form-control {
display: inline-flex;
align-items: center;
flex-shrink: 0;
width: 36px;
height: 20px;
padding: 2px;
border: none;
border-radius: 9999px;
background: light-dark(#cbd5e1, #ffffff3d);
cursor: pointer;
}
.switch-form-control[data-state="checked"] {
background: #009dfd;
}
.switch-form-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-form-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.switch-form-thumb {
display: block;
width: 16px;
height: 16px;
border-radius: 9999px;
background: #ffffff;
box-shadow: 0 1px 2px rgb(15 23 42 / 0.2);
transition: transform 150ms ease;
}
.switch-form-thumb[data-state="checked"] {
transform: translateX(16px);
}
.switch-form-submit {
height: 32px;
padding: 0 12px;
border: none;
border-radius: 6px;
background: #009dfd;
color: #ffffff;
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.switch-form-submit:hover {
background: #006ce9;
}
.switch-form-submit:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.switch-form-output {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}- Pass
name,valueandformtoHiddenInputlike you would to an<input>. The library setschecked,requiredanddisabledfrom 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: absolutestyle instead of thehiddenattribute, so that nativerequiredvalidation still works. Setposition: relativeon the Root so that it stays in place. HiddenInputis optional. Without it, the control works the same but does not submit a value.
Radio Group submits the value of the selected item:
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>
);
});.radio-group-with-form-wrapper {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
}
.radio-group-with-form-form {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
}
.radio-group-with-form-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
}
.radio-group-with-form-label {
font-size: 14px;
font-weight: 600;
color: light-dark(#0f172a, #ffffff);
}
.radio-group-with-form-item {
display: inline-flex;
align-items: center;
gap: 10px;
padding: 0;
background: none;
border: none;
font: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
text-align: left;
}
.radio-group-with-form-item:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
border-radius: 4px;
}
.radio-group-with-form-item:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.radio-group-with-form-indicator {
flex-shrink: 0;
width: 16px;
height: 16px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 9999px;
background: light-dark(#ffffff, #1b2045);
box-sizing: border-box;
}
/* A thick accent border draws the selected dot */
.radio-group-with-form-indicator[data-state="checked"] {
border: 5px solid #009dfd;
}
.radio-group-with-form-form-button {
height: 32px;
padding: 0 12px;
border: none;
border-radius: 6px;
background: #009dfd;
color: #ffffff;
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.radio-group-with-form-form-button:hover {
background: #006ce9;
}
.radio-group-with-form-form-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.radio-group-with-form-submitted {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}Next steps#
- Field, Fieldset, Checkbox, Switch and Radio Group: the API of each component.
- Controlled & Uncontrolled: read and set the value of a control.