# formular

> Build forms in React. Easy-Peasy!

Latest version **3.1.6** (published 2023-01-09) · ISC license · 0 weekly downloads

## Install

```sh
npm install formular
pnpm add formular
yarn add formular
bun add formular
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 3.1.6 |
| Published | 2023-01-09 |
| First published | 2015-06-15 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 113.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Pavel Ivanov |
| Maintainers | grammka |
| Keywords | form, formjs, react, hooks |

## Links

- npm: https://www.npmjs.com/package/formular
- Repository: https://github.com/pavelivanov/formular
- Homepage: https://github.com/pavelivanov/formular#readme
- Issues: https://github.com/pavelivanov/formular/issues
- npm.io page: https://npm.io/package/formular

## Dependencies (1)

- [fast-deep-equal](https://npm.io/package/fast-deep-equal.md) ^3.1.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 3.1.6 (latest) — 2023-01-09
- 4.0.0-beta.3 (next) — 2026-04-22
- 4.0.0-beta.2 — 2026-04-22
- 4.0.0-beta.1 — 2026-04-21
- 3.1.5 — 2023-01-09
- 3.1.4 — 2022-10-11
- 3.1.3 — 2022-07-05
- 3.1.2 — 2022-05-19
- 3.1.1 — 2022-03-11
- 3.1.0 — 2022-03-11
- 3.0.1 — 2021-04-14
- 2.6.1 — 2021-04-02
- 3.0.0 — 2021-04-02
- 2.5.6 — 2021-04-02
- 2.6.0 — 2021-03-24
- … 37 more at https://npm.io/package/formular/versions

## README

# Formular

Easy way to work with forms in React. Using React Hooks 😏

<p>❤️ Just 3kb gzip</p>
<p>❤️ React hooks</p>
<p>❤️ TypeScript</p>
<p>❤️ Changes made within form rerender only changed fields</p>


#### Installation

```
npm install formular
```


## Philosophy

There are many form libraries that works out of the box - _"import Form, Field and that's it"_. But in most projects common fields are customized by design and usage of Form, Field components become impossible. **Formular** doesn't provide inboxing components for fast start, but it provides easy way to attach form functionality to custimized fields!

For example you have your own styled `Input` component with specific logic inside

```tsx
import { useField, useFieldState } from 'formular'

const FormularInput = () => {
  const field = useField()
  const state = useFieldState(field)

  return <CustomInput value={state.value} onChange={field.set} />
}
```

`useField` is a wrapper for `new Field`:

```tsx
const useField = (opts, deps) => useMemo(() => new Field(opts), deps || [])
```

So when field's state updates FormularSelect doesn't render. Here `useFieldState` comes, it triggers react state update which call component's render.

#### This is Field, and whats about Form?

Lets update the code above to reuse Select component

```tsx
import { useField, useFieldState } from 'formular'

const FormularInput = ({ field }) => {
  const state = useFieldState(field)

  return <CustomInput value={state.value} onChange={field.set} />
}

const Auth = () => {
  const emailField = useField()
  const passwordField = useField()

  return (
    <>
      <FormularInput field={emailField} />
      <FormularInput field={passwordField} />
    </>
  )
}
```

Let's add validators and submit logic


```tsx

const required = (value) => {
  if (!value) {
    return 'Required'
  }
}

const Auth = () => {
  const emailField = useField({
    validate: [ required ],
  })
  const passwordField = useField({
    validate: [ required ],
  })

  const handleSubmit = useCallbac(async () => {
    const isEmailValid = await emailField.validate()
    const isPasswordValid = await passwordField.validate()
    
    const emailValue = emailField.state.value
    const passwordValue = passwordField.state.value
    
    const emailError = emailField.state.error
    const passwordError = passwordField.state.error
  }, [])

  return (
    <>
      <FormularInput field={emailField} />
      <FormularInput field={passwordField} />
      <button onClick={handleSubmit}>Login</button>
    </>
  )
}
```

Same could be written using `useForm`

```tsx
const Auth = () => {
  const form = useForm({
    email: [ required ],
    password: [ required ],
  })

  const handleSubmit = useCallbac(async () => {
    const isValid = await form.validate()
    
    const values = form.getValues() // { email: '', password: '' }
    const errors = form.getErrors() // { email: 'Required', password: 'Required' }
  }, [])

  return (
    <>
      <FormularInput field={emailField} />
      <FormularInput field={passwordField} />
      <button onClick={handleSubmit}>Login</button>
    </>
  )
}
```

in most cases you need submit

```tsx
const handleSubmit = useCallbac(async () => {
  try {
    const values = await form.submit() // { email: '', password: '' }
  }
  catch (errors) {} // { email: 'Required', password: 'Required' }
}, [])
```


### Validation

```
const required = (value) => {
  if (!value) {
    return 'Required'
  }
}

const uniqueEmail = async (value) => {
  const isExist = await fetch(`check-email-exist?email={value}`)
  
  if (isExists) {
    return 'Account with such email already exists'
  }
}

const field = useField({
  validate: [ required, uniqueEmail ]
})

const isValid = await field.validate()
```

☝️ `field.validate()` always async!<br />
☝️ a validator function should return `undefined` if value is valid



## Examples

- [Basics](https://codesandbox.io/s/formular-basics-cke7r)
- [Building own Input](https://codesandbox.io/s/formular-building-own-input-4qsxd)
- [Async validation](https://codesandbox.io/s/formular-async-validation-i6l4c)


## Options

#### Form

```ts
type FormOpts = {
  name?: string
  fields: {
    [key: string]: FieldOpts
  }
  initialValues?: object
}
```

#### Field

```ts
type FieldOpts = {
  name?: string
  value?: string                // initial value
  validate?: Array<Function>    // list of validators
  readOnly?: boolean
  validationDelay?: number      // adds debounce to validation
}
```


## Interfaces

#### Form

```ts
type FormEntity = {
  name?: string
  opts: FormOpts
  fields: {
    [key: string]: Field
  }
  state: {
    isValid: boolean
    isChanged: boolean
    isValidating: boolean
    isSubmitting: boolean
    isSubmitted: boolean
  }
  setState(values: Partial<State>): void
  setValues(values: object): void
  getValues(): object
  unsetValues(): void
  getErrors(): object
  async validate(): Promise<boolean>
  async submit(): Promise<object>
  on(eventName: string, handler: Function): void
  off(eventName: string, handler: Function): void
}

const form: FormEntity = useForm(opts)
```

#### Field

```ts
type FieldEntity = {
  form?: Form
  name?: string
  opts: FieldOpts
  node?: HTMLElement
  validators: Array<Function>
  readOnly: boolean
  debounceValidate: Function  // method to call validation with debounce
  state: {
    value: any
    error: any
    isChanged: boolean
    isValidating: boolean
    isValidated: boolean
    isValid: boolean
  }
  setState(values: Partial<State>): void
  setRef(node: HTMLElement): void
  unsetRef(): void
  set(value: any, opts?: { silent: boolean }): void
  unset(): void
  validate = (): CancelablePromise
  on(eventName: string, handler: Function): void
  off(eventName: string, handler: Function): void
}

const field: FieldEntity = useField(opts)
```

**Note:** `{ silent: true }` in field.set doesn't trigger events.


## Events

#### Form

```ts
form.on('state change', (state) => {
  // triggers on a form's state change
})

form.on('change', (field) => {
  // triggers on a field change
})

form.on('blur', (field) => {
  // triggers on a field blurring
})
```

#### Field

```ts
form.on('state change', (state) => {
  // triggers on a field's state change
})

field.on('set', (value) => {
  // triggers on a value set
})

field.on('change', (value) => {
  // simlink to "set"
})

field.on('unset', () => {
  // triggers on a value unset
})

field.on('start validate', () => {
  // triggers on a validation start
})

field.on('validate', (error) => {
  // triggers on a validation finish
})

field.on('blur', () => {
  // triggers on a field blurring
})
```

---
_Source: https://npm.io/package/formular · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
