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

• Replaced register with the hook-style useRegister using a positional (name, options) signature.
• useFields now returns field meta (touched, dirty, isValid) along with value and error.
• Read access is unified through useFields; there are no getValues/getErrors helpers.
• SicilianProvider context now uses useRegister and optional useFields.
• Resolver imports are namespaced: @ilokesto/sicilian/resolver/zod, /yup, /superstruct.

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 { useRegister, handleSubmit, useFields } = 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);
  };

  const nameField = useFields('name');
  const emailField = useFields('email');

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

      <div>
        <label htmlFor="email">email:</label>
        <input id="email" {...useRegister('email', { type: 'email' })} />
        {emailField.error}
      </div>

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