Introduce the sicilian

react-hook-form, a widely used form state library in frontend development, operates around refs. That often requires wrapping components with forwardRef or using useFormContext. For many React developers, that constraint can be inconvenient.

sicilian addresses these issues by building on a global state approach. It manages each input as state and helps you write forms in a controlled-component style. Sicilian uses React's Context API internally to manage form state globally, so any component can access and manipulate form state without adding a separate global state library (e.g., Redux, Zustand).

What's new in sicilian@3.1.0#

• Runtime validation support using zod (v3, v4), yup, and superstruct.
• Fixed a bug in register for type="radio".
• Added validateOptions as a general replacement for handleValidate.
• Added handleServerAction to support server actions.
• A CLI to generate code snippets quickly has been added. See the CLI usage page for details.

Installation#

sicilian can be installed using several methods listed below.

npm install @ilokesto/sicilian
pnpm add @ilokesto/sicilian
yarn add @ilokesto/sicilian
bun add @ilokesto/sicilian

Quick start#

The example below shows basic sicilian usage. It implements a simple login form including validation for email and password fields. See how the sicilian form controller manages state and displays error messages for inputs.

import { useForm } from '@ilokesto/sicilian';

export default function MySimpleForm() {
  const { register, handleSubmit, getErrors } = useForm({
    initValue: {
      name: '',
      email: ''
    },
    validator: {
      name: {
        required: { required: true, message: 'name is required' }
      },
      email: {
        required: { required: true, message: 'email is required' },
        RegExp: {
          RegExp: /^[a-zA-Z0-9+-_.]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/,
          message: 'email format is invalid'
        }
      }
    }
  });

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

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="name">name:</label>
        <input id="name" {...register({ name: 'name', type: 'text' })} />
        {getErrors('name')}
      </div>

      <div>
        <label htmlFor="email">email:</label>
        <input id="email" {...register({ name: 'email', type: 'email' })} />
        {getErrors('email')}
      </div>

      <button type="submit">login</button>
    </form>
  );
}