> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/akinon-ui/ui-kit/components/akiform.md).

# AkiForm

Akiform is a form library for React that integrates React Hook Form with Akinon UI Kit components.

It provides a seamless way to build type-safe, validated forms with minimal boilerplate.

### <mark style="color:red;">Installation</mark>

```bash
pnpm add @akinon/akiform
```

For schema-driven form building, also install:

```bash
pnpm add @akinon/akiform-builder
```

### <mark style="color:red;">Core Concepts</mark>

Akiform offers two approaches:

1. **Component-based** - Use `Akiform` and `FormItem` components with React Hook Form hooks
2. **Schema-driven** - Use `AkiformBuilder` with a declarative field schema

### <mark style="color:red;">Component-Based Usage</mark>

#### Basic Form

```tsx
import { Akiform, FormItem, useForm } from '@akinon/akiform';
import { akival, akivalResolver } from '@akinon/akiform';
import { Input } from '@akinon/ui-input';
import { Button } from '@akinon/ui-button';

interface LoginForm {
  email: string;
  password: string;
}

const validationSchema = akival.object({
  email: akival.string().email().required(),
  password: akival.string().min(8).required()
});

export const LoginForm = () => {
  const { control, handleSubmit } = useForm<LoginForm>({
    resolver: akivalResolver(validationSchema),
    defaultValues: {
      email: '',
      password: ''
    }
  });

  const onSubmit = (data: LoginForm) => {
    console.log('Form submitted:', data);
  };

  return (
    <Akiform layout="vertical" onFinish={handleSubmit(onSubmit)}>
      <FormItem control={control} name="email" label="Email">
        <Input placeholder="Enter email" />
      </FormItem>
      <FormItem control={control} name="password" label="Password">
        <Input type="password" placeholder="Enter password" />
      </FormItem>
      <Button type="primary" htmlType="submit">
        Sign In
      </Button>
    </Akiform>
  );
};
```

#### FormItem Props

| Prop               | Type                     | Description                                           |
| ------------------ | ------------------------ | ----------------------------------------------------- |
| `control`          | `Control<T>`             | React Hook Form control object                        |
| `name`             | `FieldPath<T>`           | Field name/path in the form data                      |
| `label`            | `string`                 | Field label                                           |
| `labelDescription` | `string`                 | Additional description below label                    |
| `help`             | `string`                 | Help text below input                                 |
| `tooltip`          | `TooltipProps \| string` | Tooltip for the label                                 |
| `disabled`         | `boolean`                | Disable the field                                     |
| `valuePropName`    | `string`                 | Custom value prop name (e.g., `checked` for checkbox) |

#### Akiform Props

| Prop                 | Type                                     | Default        | Description                 |
| -------------------- | ---------------------------------------- | -------------- | --------------------------- |
| `layout`             | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | Form layout                 |
| `labelAlign`         | `'left' \| 'right'`                      | -              | Label text alignment        |
| `labelCol`           | `ColProps`                               | -              | Label column layout         |
| `wrapperCol`         | `ColProps`                               | -              | Input wrapper column layout |
| `size`               | `'small' \| 'middle' \| 'large'`         | -              | Form controls size          |
| `disabled`           | `boolean`                                | -              | Disable all form fields     |
| `colon`              | `boolean`                                | -              | Show colon after label      |
| `scrollToFirstError` | `boolean \| Options`                     | -              | Auto scroll to first error  |

### <mark style="color:red;">Hooks</mark>

#### useForm

Create a form instance with React Hook Form:

```tsx
import { useForm, type UseFormProps } from '@akinon/akiform';

const { control, handleSubmit, reset, watch, setValue, getValues, formState } = 
  useForm<FormValues>({
    defaultValues: {
      name: '',
      email: ''
    },
    resolver: akivalResolver(schema)
  });
```

#### useWatch

Watch form values reactively:

```tsx
import { useWatch } from '@akinon/akiform';

const FormComponent = ({ control }) => {
  const watchedValue = useWatch({ control, name: 'fieldName' });
  const allValues = useWatch({ control });
  
  return <div>Current value: {watchedValue}</div>;
};
```

#### useController

Access field state and methods:

```tsx
import { useController } from '@akinon/akiform';

const CustomInput = ({ control, name }) => {
  const { field, fieldState } = useController({ control, name });
  
  return (
    <div>
      <input {...field} />
      {fieldState.error && <span>{fieldState.error.message}</span>}
    </div>
  );
};
```

#### useFieldArray

Manage dynamic field arrays:

```tsx
import { useFieldArray } from '@akinon/akiform';

const DynamicFields = ({ control }) => {
  const { fields, append, remove } = useFieldArray({
    control,
    name: 'items'
  });
  
  return (
    <div>
      {fields.map((field, index) => (
        <div key={field.id}>
          <FormItem control={control} name={`items.${index}.name`}>
            <Input />
          </FormItem>
          <Button onClick={() => remove(index)}>Remove</Button>
        </div>
      ))}
      <Button onClick={() => append({ name: '' })}>Add Item</Button>
    </div>
  );
};
```

### <mark style="color:red;">Validation with Akival</mark>

Use `@akinon/akival` for form validation:

```tsx
import { akival, akivalResolver } from '@akinon/akiform';

const schema = akival.object({
  username: akival.string()
    .min(3, 'Username must be at least 3 characters')
    .required('Username is required'),
  email: akival.string()
    .email('Invalid email format')
    .required('Email is required'),
  age: akival.number()
    .min(18, 'Must be at least 18')
    .required('Age is required')
});

const { control } = useForm({
  resolver: akivalResolver(schema)
});
```

### <mark style="color:red;">DevTools</mark>

Enable form debugging in development:

```tsx
import { AkiformDevTool } from '@akinon/akiform';

const Form = () => {
  const { control } = useForm();
  
  return (
    <>
      <Akiform>
        {/* form fields */}
      </Akiform>
      {process.env.NODE_ENV === 'development' && (
        <AkiformDevTool control={control} />
      )}
    </>
  );
};
```

### <mark style="color:red;">Best Practices</mark>

1. **Type your forms** - Always define TypeScript interfaces for form values
2. **Use** [**Akival**](/akinon-ui/ui-kit/utilities/akival.md) **for validation** - Consistent validation with meaningful error messages
3. **Provide default values** - Always initialize form with `defaultValues`
4. **Use FormItem for integration** - Seamless error handling with Ant Design styling

### <mark style="color:red;">Related</mark>

* [AkiformBuilder](/akinon-ui/ui-kit/components/akiform-builder.md) - Schema-driven form builder for declarative form definitions
* [Akival](/akinon-ui/ui-kit/utilities/akival.md) - Validation library for form validation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/akinon-ui/ui-kit/components/akiform.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.