Declarative Form State management container based on use-context-selector and use-reducer hook. Inspired by formik.

This library helps you create forms that are easy to maintain and expand, especially for form-heavy apps. We keep eye on modularity, flexibility, performance, accessibility, and consistency at same time. Suppresses creative solutions and keep used solution patterns without unnecessary boilerplate or redundant code. You can write easy single field form for few line of codes which could scale up to multi-page complex spacious project.

built with Vite 🖖

Example

Basic Html elements

<Form>
  <HtmlField component="input" type="range" name="age" min="1" max="100">

  <HtmlField component="select" label="Agree to T&C" name="gender">
    <option value=""></option>
    <option value="yes">Yes</option>
    <option value="no">No</option>
  </HtmlField>
</Form>

Yup Schema based form

<YupForm schema={schema}>
  <Field component={TextField} name="firstName" />
</Form>

Custom Reducer, validation, detecting requiredFields

  type data = Yup.TypeOf<schema>;
  type CustomAction = FormAction<Data> & { type: 'onDeleteItem', index: number };
  const props = {
    initialValues: { age: 33 },
    reducer: (prev: FormState<Data>, action: CustomAction) => {
      /** ... implement custom reducer logic */
      return getDefaultFormReducer()(prev, action)
    },
    validation: (data: Data) => {
      /** ... implement custom validation rules */
      return isValid ? errors : undefined
    },
    getRequired: (data: Data) => ({ firstName: true, lastName: !!data.firstName })
    onSubmit: (data: Data) => Promise.resolve(/** custom action **/),
    onStateChange(action: CustomAction<A>, prev: FormState<Data>, next:FormState<Data>, dispatch: Dispatch<FormReducerAction<D>>) => {
      /** track form changes and fire some async actions */
    }
  }

return <Form {...props}>
  <Field component={TextField} name="firstName" />
</Form>

*This is just example and you should keep some values memoized/ reference stable, bcs some form state actions are working as watchers for those values. Read more in Docs, or check Form.tsx and its useEffects(...).

Good Practices

• keep all your form login only in reducer (no "smart fields" with onChange logic overriding different field values)
• keep you data model/schema aligned as much as possible with UI = prevents mind-numbing data editing
• use input/output mapping = you can easily map JSON structures before and after those data are used with UI elements, so you don't need to fight against data structure received from API. Just like prepare data for initialValues and then process it onSubmitCall

Features

• optimized re-renders - each field is rendered only if needed by default (like Formik FastField by default but better 😉)
• standardized metadata - pre-defined ux for displaying all states of each field TODO: provide example, link mockup with explanation
• HTML input support - You can create form with minimum css (check demo code app.css)
• strongly typed - we have support for custom schema Typing + custom Actions (reducer)
• many helper functions / hooks / Components TODO: document examples
• for Yup we have automatic detection of "required fields" -
• planned support for ZOD, Ajv
• easily extensible (planned plugin system for custom reducers like history)
• #WIP async validation
• ...

Intro

demo.webm

DOCS

TODO

TODO

• use html reset form event
• review HTML field
• Flatten meta setters - error, touched
• implement/review Aria rules
• support YUP
• async validation
• html Form tag customization
• add abstraction for Formik
• use some immutable helper for setting values
  • we have to copy nested objects, so we can use some helper and deliver more secure mutations
• field validation
  • enable single field validation
• history tracking
• support ZOD
• support Ajv (Json schema / Open api)
• UI Builder...

Known issues (To Be Fixed)

1. when using HTML field, error messages are displayed via setCustomValidity(error) + reportValidity() - For the first time form is submitted, all fields going to be touched so error is displayed in random order, on second submit looks like "highest/first invalid" is focused (this is desired) = provide deeper testing and display err "first" element on page

Folders

• /dist - production build output
• /lib - library source code
• /src - example React app (dev mode)

Development

requires node >=20 and yarn.

Scripts:

• yarn build for production build
• yarn dev for development version - run dev react app with examples
• yarn test for jest - TODO