> ## Documentation Index > Fetch the complete documentation index at: https://araf.badr.co.id/llms.txt > Use this file to discover all available pages before exploring further. # Form > Composable form wrappers that connect to React Hook Form — providing consistent label, helper text, error message, and field spacing across all form elements. ## 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 ```bash npm theme={null} npm install @araf-ds/core react-hook-form @hookform/resolvers zod ``` ```bash yarn theme={null} yarn add @araf-ds/core react-hook-form @hookform/resolvers zod ``` ```bash pnpm theme={null} pnpm add @araf-ds/core react-hook-form @hookform/resolvers zod ``` *** ## Usage ```tsx theme={null} 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 (

console.log(data))}> ( Full name )} /> ( Email address We'll never share your email. )} /> ) } ``` *** ## Variants ### Basic Form Field A single field with label and validation message.

Username

```tsx theme={null} ( Username )} /> ``` ### With Helper Text Use `FormDescription` to add supporting guidance below the input.

Password Must be at least 8 characters and include a number.

```tsx theme={null} ( Password Must be at least 8 characters and include a number. )} /> ``` ### With Validation Error `FormMessage` automatically renders the Zod/RHF error message in the error state.

Email address \* Enter a valid email address

```tsx theme={null} ( Email address )} /> ``` ### Complete Form Example

Profile settings

First name

Last name

Bio

Product designer based in Jakarta.

Write a short introduction about yourself.

```tsx theme={null}

( Bio

</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

### Form

<ParamField path="form" type="UseFormReturn" required>
  The React Hook Form instance returned by `useForm()`. Passed to the internal `FormProvider`.
</ParamField>

<ParamField path="onSubmit" type="(data: T) => void" required>
  Submit handler. Typically `form.handleSubmit(handler)`.
</ParamField>

<ParamField path="className" type="string">
  Additional class names for the `<form>` element.
</ParamField>

### FormField

<ParamField path="control" type="Control" required>
  The `control` object from `useForm()`.
</ParamField>

<ParamField path="name" type="string" required>
  Field name matching the schema key.
</ParamField>

<ParamField path="render" type="({ field, fieldState }) => ReactNode" required>
  Render function receiving registered field props and validation state.
</ParamField>

### FormItem

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

### FormLabel

<ParamField path="required" type="boolean" default="false">
  Appends a red asterisk (`*`) to indicate required fields.
</ParamField>

### 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

<CardGroup cols={2}>
  <Card title="Do" icon="check" iconType="solid" color="#16A34A">
    * 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"
  </Card>

<Card title="Don't" icon="xmark" iconType="solid" color="#DC2626">
    * 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
  </Card>
</CardGroup>