Form

Overview

Full name

Email address *Enter a valid email address

Role

Select a role

Choose the user’s permission level.

The Form component provides composable wrappers — FormField, FormItem, FormLabel, FormDescription, FormMessage — that connect to React Hook Form and uniformly apply A’raf DS token-based styling to labels, helper text, and error messages.

Form is a thin integration layer, not a standalone form UI. It requires react-hook-form as a peer dependency and pairs with any A’raf DS input component (Input, Select, Checkbox, etc.).

Installation

npm install @araf-ds/core react-hook-form @hookform/resolvers zod

yarn add @araf-ds/core react-hook-form @hookform/resolvers zod

pnpm add @araf-ds/core react-hook-form @hookform/resolvers zod

Usage

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { z } from "zod"
import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormDescription,
  FormMessage,
  FormControl,
} from "@araf-ds/core"
import { Input, Select, Button } from "@araf-ds/core"

const schema = z.object({
  name: z.string().min(2, "Name must be at least 2 characters"),
  email: z.string().email("Enter a valid email address"),
  role: z.string().min(1, "Select a role"),
})

export function ProfileForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { name: "", email: "", role: "" },
  })

  return (
    <Form form={form} onSubmit={form.handleSubmit((data) => console.log(data))}>
      <FormField
        control={form.control}
        name="name"
        render={({ field }) => (
          <FormItem>
            <FormLabel>Full name</FormLabel>
            <FormControl>
              <Input placeholder="Ahmad Dani" {...field} />
            </FormControl>
            <FormMessage />
          </FormItem>
        )}
      />

      <FormField
        control={form.control}
        name="email"
        render={({ field }) => (
          <FormItem>
            <FormLabel required>Email address</FormLabel>
            <FormControl>
              <Input type="email" placeholder="[email protected]" {...field} />
            </FormControl>
            <FormDescription>We'll never share your email.</FormDescription>
            <FormMessage />
          </FormItem>
        )}
      />

      <Button type="submit">Save profile</Button>
    </Form>
  )
}

Variants

Basic Form Field

A single field with label and validation message.

Username

<FormField
  control={form.control}
  name="username"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Username</FormLabel>
      <FormControl>
        <Input placeholder="badrinteractive" {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>

With Helper Text

Use FormDescription to add supporting guidance below the input.

PasswordMust be at least 8 characters and include a number.

<FormField
  control={form.control}
  name="password"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Password</FormLabel>
      <FormControl>
        <Input type="password" {...field} />
      </FormControl>
      <FormDescription>
        Must be at least 8 characters and include a number.
      </FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>

With Validation Error

FormMessage automatically renders the Zod/RHF error message in the error state.

Email address *Enter a valid email address

<FormField
  control={form.control}
  name="email"
  render={({ field }) => (
    <FormItem>
      <FormLabel required>Email address</FormLabel>
      <FormControl>
        <Input type="email" {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>

Complete Form Example

Profile settings

First name

Last name

BioWrite a short introduction about yourself.

<Form form={form} onSubmit={form.handleSubmit(onSubmit)}>
  <div className="grid grid-cols-2 gap-3">
    <FormField name="firstName" render={...} />
    <FormField name="lastName" render={...} />
  </div>
  <FormField
    name="bio"
    render={({ field }) => (
      <FormItem>
        <FormLabel>Bio</FormLabel>
        <FormControl><Textarea rows={3} {...field} /></FormControl>
        <FormDescription>Write a short introduction.</FormDescription>
        <FormMessage />
      </FormItem>
    )}
  />
  <div className="flex justify-end gap-2">
    <Button variant="outline">Cancel</Button>
    <Button type="submit">Save changes</Button>
  </div>
</Form>

API Reference

UseFormReturn

required

The React Hook Form instance returned by useForm(). Passed to the internal FormProvider.

(data: T) => void

required

Submit handler. Typically form.handleSubmit(handler).

string

Additional class names for the <form> element.

FormField

Control

required

The control object from useForm().

string

required

Field name matching the schema key.

({ field, fieldState }) => ReactNode

required

Render function receiving registered field props and validation state.

FormItem

Container for a single field — adds consistent vertical spacing between label, control, description, and message.

FormLabel

boolean

default:"false"

Appends a red asterisk (*) to indicate required fields.

FormDescription

Renders helper text below the input in #667085 muted color.

FormMessage

Automatically reads and displays the validation error for the current field from fieldState.error. Renders nothing when there is no error.

FormControl

Binds the ARIA attributes (aria-invalid, aria-describedby) between the input and FormMessage. Always wrap your input component with FormControl.

Accessibility

FormLabel renders a <label> element with a for attribute automatically linked to the input via FormControl
FormMessage uses role="alert" so screen readers announce validation errors immediately on submit
FormControl sets aria-invalid="true" on the input when a field error exists
FormDescription is linked to the input via aria-describedby for assistive technology
Required fields should be marked with both the required prop on FormLabel and the Zod .min(1) validation rule

Do’s & Don’ts

Do

Always wrap inputs with FormControl to get correct ARIA bindings
Use FormDescription for guidance the user needs before they fill the field
Use FormMessage for validation errors triggered after interaction
Keep labels short and descriptive — “Email address” not “Please enter your email”

Don't

Don’t use FormDescription for error messages — use FormMessage instead
Don’t skip FormLabel — placeholder text alone is not accessible
Don’t place FormMessage above the input — errors should appear below
Don’t use form.handleSubmit outside the onSubmit prop — let Form manage it

Actions

Forms

Data Display

Feedback

Navigation

Layout

Charts

Icons

Form

Overview

Installation

Usage

Variants

Basic Form Field

With Helper Text

With Validation Error

Complete Form Example

API Reference

Form

FormField

FormItem

FormLabel

FormDescription

FormMessage

FormControl

Accessibility

Do’s & Don’ts

Do

Don't

​Overview

​Installation

​Usage

​Variants

​Basic Form Field

​With Helper Text

​With Validation Error

​Complete Form Example

​API Reference

​Form

​FormField

​FormItem

​FormLabel

​FormDescription

​FormMessage

​FormControl

​Accessibility

​Do’s & Don’ts

Do

Don't

Overview

Installation

Usage

Variants

Basic Form Field

With Helper Text

With Validation Error

Complete Form Example

API Reference

Form

FormField

FormItem

FormLabel

FormDescription

FormMessage

FormControl

Accessibility

Do’s & Don’ts