API リファレンス / useField

useField

FormProvider に設定されたコンテキストを購読することで、フィールドメタデータを返す React フックです。これは 最も近い FormProvider に基づいています。

1const [meta, form] = useField(name, options);

#パラメータ

name

フィールドの名前。

options

現時点での オプション は 1 つだけです。入れ子になったフォームコンテキストがあり、最も近い FormProvider からではないフィールドにアクセスしたい場合は、 formId を渡して、正しいフィールドメタデータが返されるようにすることができます。

#戻り値

meta

フィールドメタデータです。これは、 useForm フックを使用した場合の fields.fieldName に相当します。

form

フォームメタデータです。これは、 useForm または useFormMetadata フックによって返されるオブジェクトと同じものです。

#Tips

FieldName 型を使用することで、より良い型安全性を実現します。

フィールドやフォームのメタデータの型推論を改善するために、 string の代わりに FieldName<FieldSchema, FormSchema, FormError> 型を使用できます。

1import { type FormName, useFormMetadata } from '@conform-to/react';
2
3type ExampleComponentProps = {
4  name: FieldName<FieldSchema, FormSchema, FormError>;
5};
6
7function ExampleComponent({ name }: ExampleComponentProps) {
8  // これで、 'meta.value', 'meta.errors', 'form.errors' などの型が認識されます。
9  const [meta, form] = useField(name);
10
11  return <div>{/* ... */}</div>;
12}

コンポーネントをレンダリングする際には、 Conform によって提供される名前(例: fields.fieldName.name )を使用します。これは既に FieldName<FieldSchema, FormSchema, FormError> として型付けされています。これにより、 TypeScript は型が互換性があるかをチェックし、互換性がない場合に警告を出すことができます。 string を渡すこともできますが、型チェックの機能は失われます。

1import { useForm } from '@conform-to/react';
2
3function Example() {
4  const [form, fields] = useForm();
5
6  return <ExampleComponent name={fields.fieldName.name} />;
7}

しかし、 FieldName 型をより具体的にすればするほど、コンポーネントの再利用は難しくなります。もしあなたのコンポーネントがジェネリックの一部を使用しないのであれば、いつでも省略することができます。

type ExampleComponentProps = {
  // 値やエラーなどの型を気にしない場合
  name: string;
  // フィールドの値にアクセスしている場合
  name: FieldName<number>;
  // 深くネストされたフォームがあり、トップレベルの特定のフィールドにアクセスしたい場合
  name: FieldName<number, { fieldName: string }>;
  // カスタムエラータイプを持っている場合
  name: FieldName<number, any, CustomFormError>;
};