form/introduction

Build form like a pro 😎 － 100% composible fashion (ie., no render-props) of using React Hook Form with Zod.

Quick Demo

Quick Start

Form-building is incredibly hard without a proper framework for both coding and guidance. So, we provide RHF (aka. React Hook Form) on the coding side, and most importantly, we'll teach you how to use it right.

DEEP DIVE: Why is building forms hard?

In the front-end world, several classic applications are hard to build, including forms. (Frankly, compared to others, forms aren't that hard to build) They all share the same basic challenge when things get complex:

Tons of states to manage.
The relationship among states are complicated.

When the number of states exceeds a certain limit, or/and when the complexity of the relationship among states is higher than a certain threshold, it's tough to manage them, so people create another layer of solutions for better management. RHF is one of several solutions in the field of form-building.

For the framework like RHF being great and flexible, it's easy to run into many problems without proper guidance when working on complex forms, including:

Thinking RHF is incompetent and needing another framework
Still having too many states that are hard to manage, leading to considering adding another complexity like RxJS
Code seems becoming messier and more complex after using RHF
Having no idea how to use RHF to implement certain features
...

The takeaway here is that building a form requires choosing an appropriate framework, but more importantly, you need to learn how to use it correctly. This can be a longer journey than expected.

DEEP DIVE: What's RHF?

I think the introduction on RHF's site isn't ideal for beginners.

So I'll explain it better here.

Simply put: It's a headless UI framework. The longer answer:

It's more of a framework than a library because adopting it means you'll build forms in a unique way provided by RHF. Since it's a framework, it's quite extensive to learn, and migrating to other similar libraries won't be trivial.
It's also a headless UI, but it mainly provides control toolkits for form state management instead of React components. This makes it different from Radix's approach (which offers "headless UI components"), and more similar to TanStack Table.

Since teaching form-building via RHF isn't trivial, learning things progressively is a must:

On this page, you'll learn the basic concepts of RHF. Once you've mastered the fundamentals, the tutorial pages will show how RHF can solve tough design problems while keeping everything manageable.

1️⃣ Form Jargons

Understanding these jargons is critical since many APIs (including our components and RHF's documentation) and concepts refer to them frequently.

form control: sometimes called "control element" - these are elements commonly used in forms such as input, textarea, select, etc.
RHF's (API/Concept) Jargons
- form:
  - The form representation managed by RHF
  - Think of it as your form's agent that lets you perform many actions (CRUD-like operations):
    - Reset all values of all form fields
    - Set a value for a specific field
    - ...
- form state:
  - Stores various states of the form, including:
    - Whether the entire form is submitting
    - Which fields have been touched
    - Is the entire form valid (usually when all fields are valid)
    - ...
- field: Represents a specific form control as data
- field state:
  - Just like form has form state, field has field state
  - It maintains states specific to a certain field, such as:
    - Does the field have any errors?
    - Has the field been touched?
    - ...

2️⃣ Anatomy

Typically, composing a form involves these relevant family components:

<Form>
  <FormItem>
    <FormLabel/>
    <FormControl/>
    <FormDescription/>
    <FormMessage />
  </FormItem>
  {/* more <FormItem/> ... */}
</Form>

3️⃣ Your first form

Let's look at a super simple demo:

From there, we have:

4 MUST-FOLLOW rules:
- <Form>: MUST declare schema & onSubmit props
- <FormItem>: MUST have a unique name
- <FormControl>: MUST only have one child - the control element
- Submit-button MUST have type="submit"
<FormLabel>: The system automatically registers htmlFor for you (like what happens with Label)
<FormMessage>: Displays hints below the form control, such as error messages or helpful tips to help users fill out the form

More details:

onSubmit: Called AFTER the form is validated successfully. Form validity is determined by the schema
Except for <FormControl>, you can put anything inside any other family components
- For example, we put <Cta> as a direct child of <Form>

Here's the beauty of using RHF: in the demo above, if you submit without checking the checkbox, you'll see an error message. You don't manually validate the form - it just works against the schema you provided!

When submission is successful, you'll get a clean data object in the onSubmit callback - a clear representation of "What did the user fill in?":

{
  tos: true
}

Everything is straightforward in the RHF world, right? You'll explore deeper concepts in the tutorial pages.

4️⃣ Before moving forward...

Before heading to the tutorial pages, let's learn other fundamentals by exploring demos for integration with various form controls:

Let's go! For more on family components and demos showing how versatile this component can be, head to the tutorial. Or if you're experienced enough, check out the API reference page.