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.
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>
);
});.field-default {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
font-size: 14px;
}
.field-default-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.field-default-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-default-input::placeholder {
color: light-dark(#475569, #c9ddf0);
opacity: 0.7;
}
.field-default-input:focus-visible {
border-color: #009dfd;
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.field-default-description {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/fieldnpm install @leve-ui/fieldyarn add @leve-ui/fieldbun add @leve-ui/fieldpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
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>
| Part | Element | Description |
|---|---|---|
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.
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);
}Disabled#
disabled on the Root disables the input.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Field } from '@leve-ui/field';
import styles from './disabled.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Field.Root disabled class="field-disabled">
<Field.Label class="field-disabled-label">Name</Field.Label>
<Field.Input class="field-disabled-input" />
</Field.Root>
);
});.field-disabled {
font-family: inherit;
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-size: 14px;
}
.field-disabled-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.field-disabled-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-disabled-input::placeholder {
color: light-dark(#475569, #c9ddf0);
opacity: 0.7;
}
.field-disabled-input:focus-visible {
border-color: #009dfd;
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* Set by the library while the field is disabled */
.field-disabled-input[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}Required#
required on the Root makes the input required.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Field } from '@leve-ui/field';
import styles from './required.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Field.Root required class="field-required">
<Field.Label class="field-required-label">Full name</Field.Label>
<Field.Input class="field-required-input" />
</Field.Root>
);
});.field-required {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
font-size: 14px;
}
.field-required-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.field-required-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-required-input::placeholder {
color: light-dark(#475569, #c9ddf0);
opacity: 0.7;
}
.field-required-input:focus-visible {
border-color: #009dfd;
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* Mark the label of a required field with an asterisk */
.field-required-label[data-required]::after {
content: " *";
color: light-dark(#dc2626, #f87171);
}Textarea#
Use Field.Textarea for multi-line text.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Field } from '@leve-ui/field';
import styles from './textarea.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Field.Root hasDescription class="field-textarea">
<Field.Label class="field-textarea-label">Bio</Field.Label>
<Field.Textarea placeholder="I build things with Qwik." class="field-textarea-textarea" />
<Field.Description class="field-textarea-description">
Tell us about yourself.
</Field.Description>
</Field.Root>
);
});.field-textarea {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
font-size: 14px;
}
.field-textarea-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.field-textarea-textarea {
min-height: 88px;
padding: 8px 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;
resize: vertical;
}
.field-textarea-textarea::placeholder {
color: light-dark(#475569, #c9ddf0);
opacity: 0.7;
}
.field-textarea-textarea:focus-visible {
border-color: #009dfd;
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.field-textarea-description {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { control?: string; label?: string; description?: string; errorMessage?: string } Overrides the element IDs of the parts. IDs can only be overridden here (adr/0024). |
| invalid | false | boolean Marks the control as invalid ( |
| disabled | false | boolean Disables the control. |
| required | false | boolean Marks the control as required. |
| hasDescription | false | boolean Set to |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-field | Always present |
data-invalid | Present when invalid |
data-disabled | Present when disabled |
data-required | Present 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 attribute | Value |
|---|---|
data-leve-field-label | Always present |
data-invalid | Present when the Field is invalid |
data-disabled | Present when the Field is disabled |
data-required | Present when the Field is required |
Inside a Field, for points to the control.
Input#
| Prop | Default | Type |
|---|---|---|
| bind:value | – | Signal<string> A signal synced two-way with the input value. |
| invalid | false | boolean Marks the control as invalid ( |
| bind:checked | – | Signal<boolean> A signal synced two-way with the checked state (for checkbox and radio inputs). |
Also accepts all <input> attributes.
| Data attribute | Value |
|---|---|
data-leve-field-input | Always present |
data-invalid | Present when invalid |
data-disabled | Present when disabled |
data-required | Present 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#
| Prop | Default | Type |
|---|---|---|
| bind:value | – | Signal<string> A signal synced two-way with the textarea value. |
| invalid | false | boolean Marks the control as invalid ( |
Also accepts all <textarea> attributes.
| Data attribute | Value |
|---|---|
data-leve-field-textarea | Always present |
data-invalid | Present when invalid |
data-disabled | Present when disabled |
data-required | Present 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 attribute | Value |
|---|---|
data-leve-field-description | Always present |
data-invalid | Present when the Field is invalid |
data-disabled | Present when the Field is disabled |
data-required | Present when the Field is required |
ErrorMessage#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-field-error-message | Always present |
data-invalid | Present when the Field is invalid |
data-disabled | Present when the Field is disabled |
data-required | Present when the Field is required |
Inside a Field, the error message is not rendered while the Field is not invalid.
Accessibility#
Field.Labelis a native<label>whoseforpoints to the control, so it names the control and clicking it focuses the control.- The control renders
aria-describedbypointing toField.Description(whenhasDescriptionis set) and toField.ErrorMessage(while invalid), after anyaria-describedbyyou pass. - The control renders
aria-invalid="true"while invalid, and the nativedisabledandrequiredattributes. Field.ErrorMessagerendersrole="alert", so screen readers announce the error when it appears. Passrole="status"to announce it without interrupting.- A disabled control is skipped by Tab.
- Field has no keyboard interaction of its own.