https://github.com/byteclaw/forms
π Easily built forms in React using Hooks API
https://github.com/byteclaw/forms
forms hooks hooks-api-react library react validation yup-compatibility
Last synced: 5 months ago
JSON representation
π Easily built forms in React using Hooks API
- Host: GitHub
- URL: https://github.com/byteclaw/forms
- Owner: Byteclaw
- License: mit
- Created: 2018-11-19T09:57:04.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-04T21:38:48.000Z (about 3 years ago)
- Last Synced: 2025-09-17T21:48:09.956Z (5 months ago)
- Topics: forms, hooks, hooks-api-react, library, react, validation, yup-compatibility
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@byteclaw/forms
- Size: 2.34 MB
- Stars: 8
- Watchers: 3
- Forks: 0
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @byteclaw/forms
[](https://circleci.com/gh/Byteclaw/forms)
[](#contributors)
Easily create complex forms in [React](https://github.com/facebook/react).
- [Installation](#installation)
- [Yup compatibility](#yup-compatibility)
- [Requirements](#requirements)
- [Up and running example](#up-and-running-example)
- [API](#api)
- [Form](#form)
- [Field](#field)
- [FieldError](#fielderror)
- [ArrayField](#arrayfield)
- [ObjectField](#objectfield)
- [ValidationError](#validationerror)
- [useArrayField](#usearrayfield)
- [useDebouncedCallback](#usedebouncedcallback)
- [useError](#useerror)
- [useField](#usefield)
- [useForm](#useform)
- [useFormState](#useformstate)
- [useObjectField](#useobjectfield)
- [useParentField](#useparentfield)
- [useValues](#usevalues)
- [createValidatorFromYup](#createvalidatorfromyup)
- [validationErrorFromYupError](#validationerrorfromyuperror)
- [Examples](#examples)
- [Contributions](#contributions)
## Installation
```console
npm install @byteclaw/forms
#Β or using yarn
yarn add @byteclaw/forms
```
## Yup compatibility
This library supports [Yup](https://github.com/jquense/yup) validation library. In order to use it please install [Yup](https://github.com/jquense/yup) because it isn't a part of this library.
## Requirements
- `react >= 16.8.3`
## Up and running example
```js
import { Fragment } from 'react';
import {
ArrayField,
Field,
Form,
FormProvider,
ObjectField,
createValidatorFromYup,
} from '@byteclaw/forms';
import * as yup from 'yup';
const validator = createValidatorFromYup(
yup.object().shape({
productTitle: yup.string().required(),
images: yup
.array()
.of(
yup.object().shape({
title: yup.string().required(),
url: yup
.string()
.url()
.required(),
}),
)
.required(),
attributes: yup.object().shape({
color: yup
.string()
.matches(/^#[0-9a-fA-F]{6}$/)
.required(),
}),
}),
);
{}} onValidate={validator}>
{/* global error of form */}
{({ error }) => error || null}
{({ error }) => error || null}
{({ value }, dispatch) => (
{/* value can be undefined/null if is not initialized */}
{(value || []).map((val, i) => (
{({ error }) => error || null}
{({ error }) => error || null}
removeItem(i)} type="button">
Remove
))}
dispatch({ type: 'CHANGE', value: [...value, {}] })} type="button">
Add image
)}
{({ error }) => error || null}
{({ error }) => error || null}
{({ error }) => error || null}
{form => (
Save
)}
;
```
## API
### [Form](./src/components/Form.tsx)
`Form` component is a root component necessary to use Forms at all. It provides a context for all fields in a given form.
Form accepts `onValidate`, `onSubmit` and `validateOnChange` props along with standard attributes accepted by ``.
- `onValidate(values?: TValues): Promise`
- optional validation function
- in case of an error please throw [`ValidationError`](#validation-error) provided by this library
- `onSubmit(values: TValues): Promise`
- optional submit function
- it can validate form too, in case of an error throw [`ValidationError`](#validation-error) provided by this library
- `onChange(values: TValues): Promise`
- optional on change function
- `validateOnChange`
- default is `false`
- optional
- will validate form on change
### [FormProvider](./src/components/FormProvider.ts)
`FormProvider` is a way to connect to `FormState` when you need to react on something.
- `children: (state: FormState) => any`
### [Field](./src/components/Field.ts)
`Field` is a base component to construct simple widgets using `` elements. On change is debounced.
### [FieldError](./src/components/FieldError.ts)
`FieldError` is a base component if you want to render validation errors that are connected with a specific field or a form root.
To connect to a root of ObjectField/ArrayField/Form use it like this:
```jsx
{err => JSON.stringify(err, null, ' ')}
```
Or specify `name` as a name that was used by `Field` component.
### [ArrayField](./src/components/ArrayField.tsx)
`ArrayField` is a base component to construct complex fields for array values.
### [ObjectField](./src/components/ObjectField.tsx)
`ObjectField` is a base component to construct nested objects in your form.
### [ValidationError](./src/components/ValidationError.ts)
`ValidationError` is a way how to map errors to fields in your form.
### [useArrayField](./src/hooks/useArrayField.ts)
### [useDebouncedCallback](./src/hooks/useDebouncedCallback.ts)
### [useError](./src/hooks/useError.ts)
### [useForm](./src/hooks/useForm.ts)
### [useField](./src/hooks/useField.ts)
### [useFormState](./src/hooks/useFormState.ts)
### [useObjectField](./src/hooks/useObjectField.ts)
### [useParentField](./src/hooks/useParentField.ts)
### [useValues](./src/hooks/useValues.ts)
### [createValidationErrorFromYup](./src/utils/createValidationErrorFromYup.ts)
### [validationErrorFromYupError](./src/utils/validationErrorFromYupError.ts)
## Examples
- [Simple Form](./examples/SimpleForm.md)
## Contributors
| [
Michal KvasniΔΓ‘k](https://github.com/michalkvasnicak)
[π¬](#question-michalkvasnicak "Answering Questions") [π»](https://github.com/byteclaw/@byteclaw/forms/commits?author=michalkvasnicak "Code") [π¨](#design-michalkvasnicak "Design") [π](https://github.com/byteclaw/@byteclaw/forms/commits?author=michalkvasnicak "Documentation") [π‘](#example-michalkvasnicak "Examples") [π€](#ideas-michalkvasnicak "Ideas, Planning, & Feedback") [π](#review-michalkvasnicak "Reviewed Pull Requests") [β οΈ](https://github.com/byteclaw/@byteclaw/forms/commits?author=michalkvasnicak "Tests") | [
Juraj HrΓb](https://github.com/jurajhrib)
[π¬](#question-jurajhrib "Answering Questions") [π](https://github.com/byteclaw/@byteclaw/forms/issues?q=author%3Ajurajhrib "Bug reports") [π»](https://github.com/byteclaw/@byteclaw/forms/commits?author=jurajhrib "Code") [π](https://github.com/byteclaw/@byteclaw/forms/commits?author=jurajhrib "Documentation") [π€](#ideas-jurajhrib "Ideas, Planning, & Feedback") [π](#review-jurajhrib "Reviewed Pull Requests") |
| :---: | :---: |
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!
## License
MIT License