Form

Renders a form element and provides a form store to its controls.

The form is automatically validated on change and on blur. This behavior can be disabled with the validateOnChange and validateOnBlur props.

When the form is submitted with errors, the first invalid field is automatically focused thanks to the autoFocusOnSubmit prop. If it's successful, the resetOnSubmit prop ensures the form is reset to its initial values as defined by the defaultValues option on the store.

Code examples

const form = useFormStore({
  defaultValues: { username: "johndoe" },
});

<Form store={form}>
  <FormLabel name={form.names.username}>Username</FormLabel>
  <FormInput name={form.names.username} />
</Form>
const form = useFormStore({
  defaultValues: { username: "johndoe" },
});

<Form store={form}>
  <FormLabel name={form.names.username}>Username</FormLabel>
  <FormInput name={form.names.username} />
</Form>

Optional Props

`autoFocusOnSubmit`

boolean | undefined = true
boolean | undefined = true

Determines if the form should automatically focus on the first invalid field when the form is submitted.

`render`

RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | undefined
RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | undefined

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Some Ariakit components detect the type of the underlying element when they mount. If the render element's type may change while the component is mounted, pass a key⁠ prop that changes with the element type so React remounts the component with the new element. Remounting resets uncontrolled state, so keep the relevant state controlled:

<Checkbox
  key={custom ? "custom" : "native"}
  checked={checked}
  onChange={() => setChecked(!checked)}
  render={custom ? <div /> : <input />}
/>
<Checkbox
  key={custom ? "custom" : "native"}
  checked={checked}
  onChange={() => setChecked(!checked)}
  render={custom ? <div /> : <input />}
/>

Check out the Composition guide for more details.

`resetOnSubmit`

boolean | undefined = true
boolean | undefined = true

Determines if the form state should be reset to its defaultValues upon successful form submission.

`resetOnUnmount`

boolean | undefined = false
boolean | undefined = false

Determines if the form state should reset to its defaultValues when the Form component is unmounted.

`store`

FormStore<FormStoreValues> | undefined
FormStore<FormStoreValues> | undefined

Object returned by the useFormStore hook. If not provided, the closest FormProvider component's context will be used.

`validateOnBlur`

boolean | undefined = true
boolean | undefined = true

Determines if the form should invoke the validation callbacks registered with useFormValidate when a field loses focus.

`validateOnChange`

boolean | undefined = true
boolean | undefined = true

Determines if the form should invoke the validation callbacks registered with useFormValidate when the values change.

Form

Stay tuned