フォーム

バリデーションルールを使用して、ユーザーから情報を収集します。

import React from 'react';
import * as Form from '@radix-ui/react-form';
import './styles.css';

const FormDemo = () => (
  <Form.Root className="FormRoot">
    <Form.Field className="FormField" name="email">
      <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
        <Form.Label className="FormLabel">Email</Form.Label>
        <Form.Message className="FormMessage" match="valueMissing">
          Please enter your email
        </Form.Message>
        <Form.Message className="FormMessage" match="typeMismatch">
          Please provide a valid email
        </Form.Message>
      </div>
      <Form.Control asChild>
        <input className="Input" type="email" required />
      </Form.Control>
    </Form.Field>
    <Form.Field className="FormField" name="question">
      <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
        <Form.Label className="FormLabel">Question</Form.Label>
        <Form.Message className="FormMessage" match="valueMissing">
          Please enter a question
        </Form.Message>
      </div>
      <Form.Control asChild>
        <textarea className="Textarea" required />
      </Form.Control>
    </Form.Field>
    <Form.Submit asChild>
      <button className="Button" style={{ marginTop: 10 }}>
        Post question
      </button>
    </Form.Submit>
  </Form.Root>
);

export default FormDemo;

機能

ネイティブブラウザ上に構築制約バリデーションAPI。

組み込みバリデーションをサポート。

カスタムバリデーションをサポート。

バリデーションメッセージの完全なカスタマイズ。

アクセシブルなバリデーションメッセージ。

クライアントサイドとサーバーサイドのシナリオをサポート。

フォーカスは完全に管理されています。

インストール

コマンドラインからコンポーネントをインストールします。

npm install @radix-ui/react-form

構成

すべての部品をインポートして組み合わせてください。

import * as Form from '@radix-ui/react-form';

export default () => (
  <Form.Root>
    <Form.Field>
      <Form.Label />
      <Form.Control />
      <Form.Message />
      <Form.ValidityState />
    </Form.Field>

    <Form.Message />
    <Form.ValidityState />

    <Form.Submit />
  </Form.Root>
);

APIリファレンス

ルート

フォームのすべての部品を含みます。

プロパティ	型	デフォルト
`asChild`	`ブール値`	`false`
`onClearServerErrors`	`関数`	デフォルト値なし

フィールド

フィールドのラッパーです。ID/nameとラベルのアクセシビリティを自動的に処理します。

プロパティ	型	デフォルト
`asChild`	`ブール値`	`false`
`name*`	`文字列`	デフォルト値なし
`serverInvalid`	`ブール値`	デフォルト値なし

データ属性	値
`[data-invalid]`	フィールドが無効な場合に表示されます。
`[data-valid]`	フィールドが有効な場合に表示されます。

ラベル

Field部品の中にネストされている場合、自動的に接続されるラベル要素です。

プロパティ	型	デフォルト
`asChild`	`ブール値`	`false`

データ属性	値
`[data-invalid]`	フィールドが無効な場合に表示されます。
`[data-valid]`	フィールドが有効な場合に表示されます。

コントロール

Field部品の中にネストされている場合、自動的に接続されるコントロール要素（デフォルトではinput）です。

プロパティ	型	デフォルト
`asChild`	`ブール値`	`false`

データ属性	値
`[data-invalid]`	フィールドが無効な場合に表示されます。
`[data-valid]`	フィールドが有効な場合に表示されます。

メッセージ

Field部品の中にネストされている場合、指定されたコントロールに自動的に接続される（機能とアクセシビリティ）バリデーションメッセージです。組み込みとカスタムのクライアントサイドバリデーション、およびサーバーサイドバリデーションに使用できます。Fieldの外で使用する場合、フィールドに一致するnameプロパティを渡す必要があります。

Form.Message は、メッセージの表示タイミングを決定するために使用される match プロパティを受け入れます。これはネイティブのHTML妥当性状態（MDN上の ValidityState）と一致し、required、min、max などの属性に対して検証されます。指定された match がコントロールの妥当性状態において true の場合、メッセージが表示されます。

match に関数は渡すこともでき、カスタム検証ルールを指定できます。

プロパティ	型	デフォルト
`asChild`	`ブール値`	`false`
`match`	`Matcher`	デフォルト値なし
`forceMatch`	`ブール値`	`false`
`name`	`文字列`	デフォルト値なし

ValidityState

このレンダープロップコンポーネントを使用して、レンダリング時に特定のフィールドの妥当性状態にアクセスします（MDN参照）。フィールドの妥当性は、Field 内にネストされている場合は自動的に利用できます。それ以外の場合は、関連付けるために name プロパティを渡す必要があります。

プロパティ	型	デフォルト
`children`	`関数`	デフォルト値なし
`name`	`文字列`	デフォルト値なし

Submit

送信ボタン。

プロパティ	型	デフォルト
`asChild`	`ブール値`	`false`

Examples

独自のコンポーネントとの合成

asChild を使用すると、独自のコンポーネントで Form プリミティブパーツを合成できます。

<Form.Field name="name">
  <Form.Label>Full name</Form.Label>
  <Form.Control asChild>
    <TextField.Input variant="primary" />
  </Form.Control>
</Form.Field>

select などの他のタイプの制御を合成するためにも使用できます。

<Form.Field name="country">
  <Form.Label>Country</Form.Label>
  <Form.Control asChild>
    <select>
      <option value="uk">United Kingdom</option>…
    </select>
  </Form.Control>
</Form.Field>

注：現時点では、Checkbox、Select など、Radix の他のフォームプリミティブと Form を合成することはできません。解決策に取り組んでいます。

独自の検証メッセージの提供

children が提供されない場合、Form.Message は、指定された match のデフォルトのエラーメッセージをレンダリングします。

// will yield "This value is missing"
<Form.Message match="missingValue" />

独自の children を渡すことで、より意味のあるメッセージを提供できます。これは国際化にも役立ちます。

// will yield "Please provide a name"
<Form.Message match="missingValue">Please provide a name</Form.Message>

カスタム検証

上記のすべての組み込みクライアントサイド検証一致に加えて、プラットフォームの検証機能を引き続き利用しながら、独自の検証を提供することもできます。制約検証APIにある customError タイプを使用します。

Form.Message の match プロパティに独自の検証関数を渡すことができます。例を以下に示します。

<Form.Field name="name">
  <Form.Label>Full name</Form.Label>
  <Form.Control />
  <Form.Message match={(value, formData) => value !== 'John'}>
    Only John is allowed.
  </Form.Message>
</Form.Field>

match は、コントロールの現在の値を最初の引数として、FormData 全体を2番目の引数として呼び出されます。match は非同期検証を実行するために非同期関数（またはプロミスを返す関数）にすることもできます。

妥当性に基づくスタイル設定

関連部分に data-valid 属性と data-invalid 属性を追加します。これを使用して、コンポーネントを適切にスタイル設定します。Label パーツのスタイル設定例を以下に示します。

//index.jsx
import * as React from 'react';
import Form from '@radix-ui/react-form';

export default () => (
  <Form.Root>
    <Form.Field name="email">
      <Form.Label className="FormLabel">Email</Form.Label>
      <Form.Control type="email" />
    </Form.Field>
  </Form.Root>
);

/* styles.css */
.FormLabel[data-invalid] {
  color: red;
}
.FormLabel[data-valid] {
  color: green;
}

より詳細な制御のための妥当性状態へのアクセス

独自のアイコンを表示したり、定義済みのプロパティを介してコンポーネントライブラリとインターフェースするために、フィールドの生の妥当性状態にアクセスする必要がある場合があります。Form.ValidityState パーツを使用してこれを行うことができます。

<Form.Field name="name">
  <Form.Label>Full name</Form.Label>
  <Form.ValidityState>
    {(validity) => (
      <Form.Control asChild>
        <TextField.Input
          variant="primary"
          state={getTextFieldInputState(validity)}
        />
      </Form.Control>
    )}
  </Form.ValidityState>
</Form.Field>

サーバーサイド検証

このコンポーネントは、同じ Form.Message コンポーネントを使用してサーバーサイド検証もサポートしています。クライアント側の整合ロジックに関係なくメッセージを強制的に表示させる forceMatch プロパティを渡すことで、クライアントサイドエラーに対して定義したメッセージを再利用できます。

クライアント側にメッセージが存在しない場合は、match を使用せずに Form.Message をレンダリングすることもできます。serverInvalid ブールプロパティを Form.Field パーツに渡すことで、フィールドが無効としてマークされます。

サーバーサイドエラー処理の例を以下に示します。

import * as React from 'react';
import * as Form from '@radix-ui/react-form';

function Page() {
  const [serverErrors, setServerErrors] = React.useState({
    email: false,
    password: false,
  });

  return (
    <Form.Root
      // `onSubmit` only triggered if it passes client-side validation
      onSubmit={(event) => {
        const data = Object.fromEntries(new FormData(event.currentTarget));

        // Submit form data and catch errors in the response
        submitForm(data)
          .then(() => {})
          /**
           * Map errors from your server response into a structure you'd like to work with.
           * In this case resulting in this object: `{ email: false, password: true }`
           */
          .catch((errors) => setServerErrors(mapServerErrors(errors)));

        // prevent default form submission
        event.preventDefault();
      }}
      onClearServerErrors={() =>
        setServerErrors({ email: false, password: false })
      }
    >
      <Form.Field name="email" serverInvalid={serverErrors.email}>
        <Form.Label>Email address</Form.Label>
        <Form.Control type="email" required />
        <Form.Message match="valueMissing">
          Please enter your email.
        </Form.Message>
        <Form.Message match="typeMismatch" forceMatch={serverErrors.email}>
          Please provide a valid email.
        </Form.Message>
      </Form.Field>

      <Form.Field name="password" serverInvalid={serverErrors.password}>
        <Form.Label>Password</Form.Label>
        <Form.Control type="password" required />
        <Form.Message match="valueMissing">
          Please enter a password.
        </Form.Message>
        {serverErrors.password && (
          <Form.Message>
            Please provide a valid password. It should contain at least 1 number
            and 1 special character.
          </Form.Message>
        )}
      </Form.Field>

      <Form.Submit>Submit</Form.Submit>
    </Form.Root>
  );
}

Form.Root パーツの onClearServerErrors コールバックプロパティを使用して、サーバーエラーをクリアする必要があります。フォームが再送信される前と、フォームがリセットされるときに、サーバーエラーがクリアされます。

さらに、単一のサーバーエラーをリセットするタイミングを制御できます。たとえば、ユーザーがメールアドレスを編集するとすぐに、メールアドレスのサーバーエラーをリセットできます。

<Form.Field name="email" serverInvalid={serverErrors.email}>
  <Form.Label>Email address</Form.Label>
  <Form.Control
    type="email"
    onChange={() => setServerErrors((prev) => ({ ...prev, email: false }))}
  />
  <Form.Message match="missingValue">Please enter your email.</Form.Message>
  <Form.Message match="typeMismatch" forceMatch={serverErrors.email}>
    Please provide a valid email.
  </Form.Message>
</Form.Field>

アクセシビリティ

このコンポーネントは、検証に「インラインエラー」パターンに従います。

Form.Field で指定された name を使用して、ラベルとコントロールが関連付けられます。
1つ以上のクライアントサイドエラーメッセージが表示されると、それらは自動的に対応するコントロールと関連付けられ、それに応じてアナウンスされます。
最初の無効なコントロールにフォーカスが移動します。

前へドロップダウンメニュー

次へホバーカード

GitHubでこのページを編集します。

概要

ガイド

コンポーネント

ユーティリティ

フォーム

機能