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.

Installation

pnpm add @akinon/akiform

For schema-driven form building, also install:

pnpm add @akinon/akiform-builder

Core Concepts

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

Component-Based Usage

Basic Form

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

Hooks

useForm

Create a form instance with React Hook Form:

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:

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:

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:

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>
  );
};

Validation with Akival

Use @akinon/akival for form validation:

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)
});

DevTools

Enable form debugging in development:

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

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

Best Practices

1. Type your forms - Always define TypeScript interfaces for form values

2. Use Akival 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

Related

• AkiformBuilder - Schema-driven form builder for declarative form definitions

• Akival - Validation library for form validation