React any shape form

Lightweight form library focused on ease of use. This library was inspired by antd form component and react-hook-form.

Features

• Small size
• Type-friendly, all components and hooks fully typed
• Ease to use, you need only createForm method to get all the functionality
• Build in promise based validation, you can easy use your own promise function to validate fields
• No extra re-renders
• useWatch, useField, useArrayField, useFieldErrors hooks
• Access to form state in any place of application, even outside of form component

Docs and examples - https://react-any-shape-form.vercel.app/

Get started

Install:

npm i react-any-shape-form

Use it like this:

import { createForm } from 'react-any-shape-form';

const MyForm = createForm({
  name: 'Rina',
  age: 24,
})

const MyComponent = () => 
  <MyForm onFinish={(state) => {
    alert(JSON.stringify(state, undefined, 2));
  }}>
    <MyForm.Item
      name="name"
      label="Name"
      onChange={value => value}
      rules={[
        {
          required: true,
          message: 'Name is required',
          validateTrigger: ['onFinish']
        },
      ]}
    >
      {({ value, onChange }) =>
        <input value={value} onChange={e => onChange(e.target.value)} />
      }
    </MyForm.Item>
    <MyForm.Item name="age">
      {({ value, onChange }) =>
        <input type="number" value={value} onChange={(e) => onChange(+e.target.value)} />
      }
    </MyForm.Item>
    <button type="submit">
      Submit button
    </button>
  </MyForm>

You can find more examples in docs

Form props

Field	Type	Description	Default
initialState	Object	Predefined fields value	{}
CSSPrefix	string	Prefix for css classes	'form'
id	string	html form id	undefined
children	ReactNode

Form.Item props

Field	Type	Description	Default
children	FC or ReactElement	Function/component with value, onChange props	{}
label	ReactNode	Field label
rules	ValidationRule[]	Validation rule
onChange	(value: Value, event?: unknown) => any	Triggers on field state changes
onInvalid	(errors: ValidationError[], value: Value) => void	Triggers on validation error
renderLabel	(value: Value, formItemId?: string) => ReactElement	Customize label
renderError	(error: ValidationError<Value>) => ReactElement	Customize error

Styling

No CSS by default. You need to style form by you own. You can change classes prefix (.form by default) using CSSPrefix property. You can use renderLabel to customize <label> and renderError for customize form error message.

CSS classes:

.form - <form> tag class.

.form__form-item - form item wrapper

.form__form-item__label - form item label (<label> tag)

.form__form-item__error - form item error

Look at ./storybook/styles.css as example.

Validation

You can pass array of validation rules to Form.Item. Don't forget to set error message or return Promise.reject('your-error-message'). You can control validation trigger using validationTrigger: ["onChange"] - trigger fires if value changed (debounced by 300ms) ["onFinish"] - trigger fires only after form submit

[
  {
    // throw an error if field value is undefined
    required: true,
    message: "Age is required",
  },
  {
    // if value < 18
    min: 18,
    type: "number",
    message: "some message",
  },
  {
    // if String().length > 100
    max: 100,
    type: "string",
    message: "some error",
  },
  {
    // if myPattern.test() === false
    type: "regexp",
    pattern: myPattern,
  },
  {
    // If value is not an email address
    type: "email",
  },
  {
    // if myValidator function throw an error or return Promise.reject
    validator: myValidator,
    message: "some error",
  },
];

Hooks

• Form.useWatch - get actual field value

const MyForm = createForm({
  name: 'Rina',
  age: 24,
})

const SomeComponent = () => {
  const name = MyForm.useWatch('name');
  ...
}

• Form.useField - get control over field state

const [name, setName] = MyForm.useField('name');

• Form.useFieldErrors - get actual field validation errors and validation status

const { errors, status } = MyForm.useFieldErrors('name');

• Form.useArrayField - get control over array field

const MyForm = createForm({
  userIds: [] as string[]
})

const SomeComponent = () => {
  const { fields, append, delete } = MyForm.useArrayField('userIds');
  
  return (
    <>
      {fields.map((field, index) =>
        <div key={index}>
          <input value={field} onChange={e => update(index, e.target.value)} />
          <button type="button" onClick={() => remove(index)}>Remove</button>
        </div>
      )}
      <button type="button" onClick={() => append("")}>
        Add
      </button>
    </>
  )
}