API Reference / useField

useField

A React hook that returns the field metadata by subscribing to the context set on the closest FormProvider.

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

#Parameters

name

The name of the field.

options

Optional with only one option at the moment. If you have a nested form context and you would like to access a field that are not from the closest FormProvider, you can pass a formId to make sure the right field metadata is returned.

#Returns

meta

The field metadata. This is equivalent to fields.fieldName with the useForm hook.

form

The form metadata. It is the same object as the one returned by the useForm or useFormMetadata hook.

#Tips

Better type-safety with the FieldName type

You can use the FieldName<FieldSchema, FormSchema, FormError> type instead of string to improve the type inference of the field and form metadata returned.

1import { type FormName, useFormMetadata } from '@conform-to/react';
2
3type ExampleComponentProps = {
4  name: FieldName<FieldSchema, FormSchema, FormError>;
5};
6
7function ExampleComponent({ name }: ExampleComponentProps) {
8  // Now it recognize the type of `meta.value`, `meta.errors`, `form.errors` etc
9  const [meta, form] = useField(name);
10
11  return <div>{/* ... */}</div>;
12}

When rendering your component, you will use the name provided by Conform, such as fields.fieldName.name which is already typed as FieldName<FieldSchema, FormSchema, FormError>. This allows typescript to check if the type is compatible and warn you if it doesn't. You can still pass a string, but you will lose the ability for type checking.

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

However, the more specific you made with the FieldName type, the harder it is to reuse the component. If your component have no use for some of the generics, you can always omit them.

type ExampleComponentProps = {
  // If you don't care about the type of value or errors etc
  name: string;
  // If you are accessing the field value
  name: FieldName<number>;
  // If you have a deeply nested form and wanted to access a specific fields at the top
  name: FieldName<number, { fieldName: string }>;
  // If you have a custom error type
  name: FieldName<number, any, CustomFormError>;
};