ドキュメントを検索

フォーム

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.InputとField.Textareaはネイティブの<input>および<textarea>要素をレンダリングします。CheckboxとSwitchも同じ方法でFieldに組み込めます。

Fieldがコントロールに設定するもの#

Field.Rootがフィールドの信頼できる唯一の情報源(Single Source of Truth)となります。コントロールはこれを読み取り、属性自体をレンダリングします。

Field.Rootのpropコントロール上の属性
(生成されたID)Field.Labelがコントロールを指すようにするためのid
hasDescriptionField.Descriptionを参照するaria-describedby
invalidaria-invalid="true"およびdata-invalid。aria-describedbyはField.ErrorMessageを参照
disableddisabledおよび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>
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は関連するコントロールを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>
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>
  );
});

ネイティブフォーム送信#

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>
  );
});
  • <input>に対して行うのと同様に、name、value、formをHiddenInputに渡します。ライブラリはコンポーネントの状態に基づいてchecked、required、disabledを設定します。
  • hidden inputは支援技術から隠され、タブ順序にも含まれません。hidden属性の代わりにインラインのposition: absoluteスタイルで視覚的に隠されるため、ネイティブのrequired検証が機能し続けます。配置を保つためにRootにposition: relativeを設定してください。
  • HiddenInputは任意です。これがない場合でもコントロールは同じように動作しますが、値は送信されません。

Radio Groupは選択された項目の値を送信します:

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>
  );
});

次のステップ#