fielder/README.md

A field-first form library for React and React Native

<p align="center">
  <img alt="Fielder logo" src="https://github.com/andyrichardson/fielder/blob/master/docs/src/assets/readme-logo.svg?raw=true" width="150px" />
</p>

<h1 align="center">Fielder</h1>
<p align="center"><i>A field-first form library for React and React Native.</i></p>

<p align="center">
  <a href="https://github.com/andyrichardson/fielder/actions">
    <img src="https://img.shields.io/github/checks-status/andyrichardson/fielder/master.svg" alt="build" />
  </a>
  <a href="https://npmjs.com/package/fielder">
    <img src="https://img.shields.io/github/package-json/v/andyrichardson/fielder.svg" alt="version" />
  </a>
  <a href="https://bundlephobia.com/result?p=fielder">
    <img src="https://img.shields.io/bundlephobia/minzip/fielder.svg" alt="size" />
  </a>
  <a href="https://codecov.io/gh/andyrichardson/fielder">
    <img src="https://img.shields.io/codecov/c/github/andyrichardson/fielder.svg" alt="coverage">
  </a>
  <a href="https://fielder.andyrichardson.dev">
    <img src="https://img.shields.io/badge/docs-visit-orange" alt="docs">
  </a>
</p>

# About

_Fielder_ is a form library for React and React Native that has been built from the ground up with a [field-first approach to validation](https://dev.to/andyrichardsonn/why-we-need-another-form-library-fielder-4eah).

## Features

⚡️ **Synchronous validation** - _no cascading renders_

🛎 **Validation events** - _validation can differ per event (change, blur, submit, etc.)_

🪝 **Hooks that work** - _hooks respond to validation changes_

🧠 **Evolving schemas** - _validation logic evolves with the UI_

## Basic usage

### Install Fielder

Add Fielder to your project.

```sh
npm i fielder
```

### Import the module

Use `fielder` or `fielder/preact`.

```tsx
// React
import { useForm, ... } from 'fielder';

// Preact
import { useForm, ... } from 'fielder/preact';
```

### Set up a form

Use the `useForm` hook to create a form.

```tsx
const myForm = useForm();

return <FielderProvider value={myForm}>{children}</FielderProvider>;
```

### Create some fields

Use the `useField` hook to create a field.

```tsx
const [usernameProps, usernameMeta] = useField({
  name: 'username',
  initialValue: '',
  validate: useCallback(({ value }) => {
    if (!value) {
      throw Error('Username is required!');
    }
  }, []),
});

return (
  <>
    <input type="text" {...usernameProps} />
    <span>{usernameMeta.error}</span>
  </>
);
```

### Additional info

Once you're all set up, be sure to check out [the guides](http://fielder.andyrichardson.dev/guides/getting-started) for a deeper dive!

## Additional resources

For more info, tutorials and examples, visit the **[official docs site](https://fielder.andyrichardson.dev/)**!

Also check out:

- [[Article] Why we need another form library](https://dev.to/andyrichardsonn/why-we-need-another-form-library-fielder-4eah)
- [[Benchmark] Fielder vs Formik](https://github.com/andyrichardson/fielder-benchmark)
- [[Video] Getting started with Fielder](https://www.youtube.com/watch?v=wSorSlCkJwk)