AkiForm Builder

AkiformBuilder provides a schema-driven approach to form creation, automatically rendering fields based on a declarative configuration.

It builds on top of Akiform and React Hook Form.

Installation

pnpm add @akinon/akiform-builder

Basic Usage

import { AkiformBuilder, field, type FormField } from '@akinon/akiform-builder';
import { akival } from '@akinon/akival';

interface UserForm {
  name: string;
  email: string;
  role: string;
}

const formFields: FormField<UserForm>[] = [
  field<UserForm>()
    .key('name')
    .type('text')
    .label('Name')
    .placeholder('Enter name')
    .validation(akival.string().required())
    .build(),
  field<UserForm>()
    .key('email')
    .type('text')
    .label('Email')
    .placeholder('Enter email')
    .validation(akival.string().email().required())
    .build(),
  field<UserForm>()
    .key('role')
    .type('select')
    .label('Role')
    .placeholder('Select role')
    .options([
      { label: 'Admin', value: 'admin' },
      { label: 'User', value: 'user' },
      { label: 'Guest', value: 'guest' }
    ])
    .build()
];

export const UserFormPage = () => {
  const handleSubmit = (values: UserForm) => {
    console.log('Form values:', values);
  };

  return (
    <AkiformBuilder
      fields={formFields}
      layout="vertical"
      onSubmit={handleSubmit}
    />
  );
};

Props

Prop	Type	Description
fields	FormField<T>[]	Array of field definitions
onSubmit	(values: T) => void	Form submission handler
layout	'vertical' | 'horizontal' | 'inline'	Form layout
layoutOptions	LayoutOptions	Label/wrapper column configuration
showResetButton	boolean	Show reset button
onReset	FormEventHandler	Reset handler
controlled	boolean	Enable controlled mode
values	T	Controlled form values
onValueChange	(values: T) => void	Value change callback
submitButtonProps	ButtonProps	Submit button customization
resetButtonProps	ButtonProps	Reset button customization
fieldErrors	ApiFieldError[]	API field errors to display
onFieldErrorsClear	() => void	Clear field errors callback

Field Builder API

Use the field() builder for type-safe field definitions:

import { field } from '@akinon/akiform-builder';

field<FormValues>()
  .key('fieldName')           // Field key (required)
  .type('text')               // Field type (required)
  .label('Label')             // Display label
  .placeholder('Placeholder') // Input placeholder
  .defaultValue('default')    // Default value
  .validation(schema)         // Akival validation schema
  .config({ disabled: false })// Field configuration
  .tooltip('Help text')       // Tooltip content
  .help('Help message')       // Help text below field
  .labelDescription('Extra')  // Label description
  .build()

Field Types

Text

field<FormValues>()
  .key('name')
  .type('text')
  .label('Name')
  .placeholder('Enter name')
  .build()

Number

field<FormValues>()
  .key('age')
  .type('number')
  .label('Age')
  .placeholder('Enter age')
  .build()

Select

field<FormValues>()
  .key('country')
  .type('select')
  .label('Country')
  .placeholder('Select country')
  .options([
    { label: 'Turkey', value: 'TR' },
    { label: 'United States', value: 'US' },
    { label: 'Germany', value: 'DE' }
  ])
  .build()

Date

field<FormValues>()
  .key('birthDate')
  .type('date')
  .label('Birth Date')
  .placeholder('Select date')
  .build()

Date with Time

field<FormValues>()
  .key('scheduledAt')
  .type('date')
  .label('Scheduled At')
  .showTime(true)
  .build()

Checkbox

field<FormValues>()
  .key('acceptTerms')
  .type('checkbox')
  .label('I accept the terms and conditions')
  .build()

Textarea

field<FormValues>()
  .key('description')
  .type('textarea')
  .label('Description')
  .placeholder('Enter description')
  .build()

Custom

field<FormValues>()
  .key('custom')
  .type('custom')
  .label('Custom Field')
  .render(({ field, control, formValues }) => (
    <MyCustomComponent
      control={control}
      name={field.key}
      formValues={formValues}
    />
  ))
  .build()

Layout Fields

Section

Group fields into collapsible sections:

field<FormValues>()
  .key('personalInfo')
  .type('section')
  .label('Personal Information')
  .collapsible(true)
  .defaultExpanded(true)
  .fields([
    field<FormValues>().key('firstName').type('text').label('First Name').build(),
    field<FormValues>().key('lastName').type('text').label('Last Name').build()
  ])
  .build()

Row and Column

Create multi-column layouts:

field<FormValues>()
  .key('addressRow')
  .type('row')
  .rowProps({ gutter: 16 })
  .columnFields([
    field<FormValues>()
      .key('cityCol')
      .type('column')
      .columnProps({ span: 12 })
      .fields([
        field<FormValues>().key('city').type('text').label('City').build()
      ])
      .build(),
    field<FormValues>()
      .key('zipCol')
      .type('column')
      .columnProps({ span: 12 })
      .fields([
        field<FormValues>().key('zipCode').type('text').label('Zip Code').build()
      ])
      .build()
  ])
  .build()

Field Array

Dynamic repeatable fields:

field<FormValues>()
  .key('items')
  .type('fieldArray')
  .label('Items')
  .defaultExpanded(true)
  .fields([
    field<FormValues>().key('name').type('text').label('Item Name').build(),
    field<FormValues>().key('quantity').type('number').label('Quantity').build()
  ])
  .build()

Conditional Fields

Use .config() for dynamic visibility and disabled states:

field<FormValues>()
  .key('otherReason')
  .type('textarea')
  .label('Other Reason')
  .config({
    // Show only when reason is 'other'
    visible: (formValues) => formValues.reason === 'other',
    // Disable when form is locked
    disabled: (formValues) => formValues.isLocked
  })
  .build()

Controlled Mode

For external state management:

const [formValues, setFormValues] = useState<FormValues>({
  name: '',
  email: ''
});

<AkiformBuilder
  fields={fields}
  controlled
  values={formValues}
  onValueChange={setFormValues}
  onSubmit={handleSubmit}
/>

API Field Errors

Display server-side validation errors:

const [fieldErrors, setFieldErrors] = useState<ApiFieldError[]>([]);

const handleSubmit = async (values: FormValues) => {
  try {
    await api.submit(values);
  } catch (error) {
    setFieldErrors([
      { field: 'email', message: 'Email already exists' }
    ]);
  }
};

<AkiformBuilder
  fields={fields}
  fieldErrors={fieldErrors}
  onFieldErrorsClear={() => setFieldErrors([])}
  onSubmit={handleSubmit}
/>

Complete Example

import { AkiformBuilder, field, type FormField } from '@akinon/akiform-builder';
import { akival } from '@akinon/akival';

interface ProductForm {
  name: string;
  sku: string;
  price: number;
  category: string;
  description: string;
  isActive: boolean;
  publishDate: Date | null;
}

const productFormFields: FormField<ProductForm>[] = [
  field<ProductForm>()
    .key('basicInfo')
    .type('section')
    .label('Basic Information')
    .collapsible(true)
    .defaultExpanded(true)
    .fields([
      field<ProductForm>()
        .key('name')
        .type('text')
        .label('Product Name')
        .placeholder('Enter product name')
        .validation(akival.string().required('Product name is required'))
        .build(),
      field<ProductForm>()
        .key('sku')
        .type('text')
        .label('SKU')
        .placeholder('Enter SKU')
        .validation(akival.string().required('SKU is required'))
        .build()
    ])
    .build(),
  field<ProductForm>()
    .key('pricingRow')
    .type('row')
    .rowProps({ gutter: 16 })
    .columnFields([
      field<ProductForm>()
        .key('priceCol')
        .type('column')
        .columnProps({ span: 12 })
        .fields([
          field<ProductForm>()
            .key('price')
            .type('number')
            .label('Price')
            .placeholder('0.00')
            .validation(akival.number().min(0).required())
            .build()
        ])
        .build(),
      field<ProductForm>()
        .key('categoryCol')
        .type('column')
        .columnProps({ span: 12 })
        .fields([
          field<ProductForm>()
            .key('category')
            .type('select')
            .label('Category')
            .placeholder('Select category')
            .options([
              { label: 'Electronics', value: 'electronics' },
              { label: 'Clothing', value: 'clothing' },
              { label: 'Books', value: 'books' }
            ])
            .build()
        ])
        .build()
    ])
    .build(),
  field<ProductForm>()
    .key('description')
    .type('textarea')
    .label('Description')
    .placeholder('Enter product description')
    .build(),
  field<ProductForm>()
    .key('publishDate')
    .type('date')
    .label('Publish Date')
    .showTime(true)
    .build(),
  field<ProductForm>()
    .key('isActive')
    .type('checkbox')
    .label('Product is active')
    .build()
];

export const ProductFormPage = () => {
  const handleSubmit = (values: ProductForm) => {
    console.log('Product saved:', values);
  };

  return (
    <AkiformBuilder
      fields={productFormFields}
      layout="vertical"
      onSubmit={handleSubmit}
      showResetButton
      submitButtonProps={{ children: 'Save Product' }}
      resetButtonProps={{ children: 'Reset' }}
    />
  );
};

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. Group related fields - Use sections for better organization

4. Use controlled mode sparingly - Only when external state sync is required

5. Handle API errors - Display server-side validation with fieldErrors

Related

• Akiform - Component-based form building with React Hook Form integration

• Akival - Validation library for form validation