フォーム
FieldとFieldsetを使用してフォームコントロールのラベル付け、説明、バリデーションを行い、ネイティブフォームで送信します。
Field#
Fieldはフォームコントロールをラベル、説明、エラーメッセージと接続します。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とField.Textareaはネイティブの<input>および<textarea>要素をレンダリングします。CheckboxとSwitchも同じ方法でFieldに組み込めます。
Fieldがコントロールに設定するもの#
Field.Rootがフィールドの信頼できる唯一の情報源(Single Source of Truth)となります。コントロールはこれを読み取り、属性自体をレンダリングします。
| Field.Rootのprop | コントロール上の属性 |
|---|---|
| (生成されたID) | Field.Labelがコントロールを指すようにするためのid |
hasDescription | Field.Descriptionを参照するaria-describedby |
invalid | aria-invalid="true"およびdata-invalid。aria-describedbyはField.ErrorMessageを参照 |
disabled | disabledおよびdata-disabled |
required | ネイティブ要素でのrequired、CheckboxおよびSwitchでのaria-required |
Rootはスタイル設定用にdata-invalid、data-disabled、data-requiredも公開します。
Qwikはサーバー上でドキュメント順にパーツをレンダリングし、コントロールはその後にあるパーツよりも前にレンダリングされるため、これに伴い以下のルールが適用されます。
Field.Descriptionを描画するときはhasDescriptionを設定してください。設定しない場合、コントロールはそれによって説明されません。Field.ErrorMessageはフィールドが無効な間のみ描画してください。コントロールはその時のみそれを参照します。- Rootでidを上書き。Field内ではコントロール自身の
idは使用されません。代わりに、ids={{ control: 'email' }}のようにidsをField.Rootに渡してください。 - 状態の合成。コントロールに設定された
disabledとrequiredはFieldに設定されたものと合わせて適用され、aria-describedbyに渡したidは保持されます。
すべてのコントロールはFieldなしでも動作します。Fieldの外部では、独自のid(または生成されたID)と、独自のdisabledおよびrequired propsを使用します。
CheckboxまたはSwitchとの併用#
複数のパーツで構成されるコントロールの場合、Fieldはインタラクティブなパーツ(Checkbox.Control、Switch.Control)と接続するため、Field.Labelがその名前(アクセシブルネーム)となります。
<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は関連するコントロールを1つのラベルの下にグループ化します。ネイティブの<fieldset>と<legend>を描画するため、グループにはLegendによる名前が付けられます。Fieldset.Rootのdisabledは、ネイティブとleve-uiコントロールの両方を含む内部のすべてのフォームコントロールを無効化し、両方のパーツが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;
}ネイティブフォーム送信#
Switch、Checkbox、Radio Groupは、内部パーツをスタイル設定できるように<button>(またはroleを持つ要素)から構築されています。これらの要素は単体ではネイティブフォームに参加しません。フォーム送信やFormDataに値を含めるには、HiddenInputパーツを追加します:
<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);
}<input>に対して行うのと同様に、name、value、formをHiddenInputに渡します。ライブラリはコンポーネントの状態に基づいてchecked、required、disabledを設定します。- hidden inputは支援技術から隠され、タブ順序にも含まれません。
hidden属性の代わりにインラインのposition: absoluteスタイルで視覚的に隠されるため、ネイティブのrequired検証が機能し続けます。配置を保つためにRootにposition: relativeを設定してください。 HiddenInputは任意です。これがない場合でもコントロールは同じように動作しますが、値は送信されません。
Radio Groupは選択された項目の値を送信します:
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);
}次のステップ#
- Field、Fieldset、Checkbox、Switch、Radio Group: 各コンポーネントのAPI。
- Controlled & Uncontrolled: コントロールの値の読み取りと設定。