@jalik/react-form

Why using this lib ?

There are other well established solutions like Formik, React-Hook-Form, Redux Form...
This lib aims to provide the best experience for developers (DX) and users (UX) when creating advanced forms in React (have a look at the features below).
If you feel concerned, then it's all for you :)

Features

Fields props initialization at form level (optional)
Management of field state and updates (value and onChange)
Tracking of modified fields
Tracking of touched fields
Various form status info (modified, disabled, validating, submitting...)
Form loading using promise (optional)
Auto-disabling fields until the form is initialized
Auto-disabling fields when the form is disabled, not modified, validating or submitting
Parsing of field value when modified (smart typing or custom parser)
Replacement of empty string by null on field change and form submit
Trim values on form submitting
Field validation on change (optional)
Field validation on init/load (optional)
Field validation on touch (optional)
Field validation on submitting (optional)
Field and form validation using a custom function or schema (like yup)
Form and field errors handling
Reset form or fields
Handling form submission errors and retries
Compatible with custom components libraries
TypeScript declarations ♥

Sandbox

You can play with the lib here: https://codesandbox.io/s/jalik-react-form-demo-wx6hg?file=/src/components/UserForm.js

Installing

npm i @jalik/react-form

yarn add @jalik/react-form

Creating a form

import { Button, Field, Form, useForm } from '@jalik/react-form'

/**
 * Authenticates by username and password.
 * @param username
 * @param password
 */
function authenticate (username, password) {
  return fetch('https://www.mysite.com/auth', {
    method: 'POST',
    body: JSON.stringify({
      username,
      password
    }),
    headers: { 'content-type': 'application/json' }
  })
}

function SignInForm () {
  const form = useForm({
    initialValues: {
      username: '',
      password: ''
    },
    // onSubmit needs to return a promise,
    // so the form is aware of the submit state.
    onSubmit: (values) => authenticate(values.username, values.password)
  })

  return (
    // Using the provided components allows writing code faster while keeping it very concise.
    // <Field> and other components must be nested in a <Form> with the form context. 
    <Form context={form}>
      <Field name="username" />
      <Field name="password" />
      <Button type="submit">Sign in</Button>
    </Form>
  )
}

Loading a form

There are several ways to load a form:

Loading values inside or outside the form component ;
Loading values using the load option of useForm() ;

Loading values inside the form component

import { Button, Field, Form, useForm } from '@jalik/react-form'
import { useEffect, useState } from 'react'
import { useParams } from 'react-router'

function UserFormPage () {
  const params = useParams()
  const [user, setUser] = useState(null)

  // Load user and call setUser(user)...

  const form = useForm({
    // initialValues must be null (or omitted) at first,
    // so the form will understand that it will be initialized later.
    initialValues: user,
    reinitialize: true,
    onSubmit: async (values) => ({ saved: true }),
  })

  return (
    <Form context={form}>
      <Field name="firstName" />
      <Field name="lastName" />
      <Button type="submit">Save</Button>
    </Form>
  )
}

Loading values using the `load` option in `useForm()`

import { Button, Field, Form, useForm } from '@jalik/react-form'
import { useCallback } from 'react'

function loadUser (id) {
  return fetch(`/api/user/${id}`).then((resp) => resp.json())
}

function UserFormPage (props) {
  const form = useForm({
    // initialValues must be null (or omitted) at first,
    // so the form will understand that it will be initialized later.
    initialValues: null,
    // WARNING: load is called every time it changes,
    // in this case the form will be updated when the id changes.
    // Note that all fields are disabled during loading.
    load: useCallback(() => loadUser(1337), []),
    onSubmit: async (values) => ({ saved: true }),
  })

  return (
    <Form context={form}>
      <Field name="firstName" />
      <Field name="lastName" />
      <Button type="submit">Save</Button>
    </Form>
  )
}

Validating a form

Validating using a schema

Form validation using a schema needs a small amount of work.
Here we use @jalik/schema to validate the form using a schema, but it is possible to use any lib (yup, joi...).

import { Button, Field, FieldError, Form, useForm } from '@jalik/react-form'
import Schema from '@jalik/schema'

/**
 * Returns field props based on schema constraints.
 * @param schema
 */
export function createFieldInitializer (schema) {
  // function called by initializeField
  return (name) => {
    const field = schema.getField(name)
    return field ? {
      required: field.isRequired()
    } : null
  }
}

/**
 * Validates the field using the schema.
 * @param schema
 */
export function createFieldValidator (schema) {
  // function called by validateField
  return async (name, value) => {
    schema.getField(name).validate(value)
  }
}

/**
 * The function returned validates the form (all fields) using the schema.
 * @param schema
 */
export function createFormValidator (schema) {
  // function called by validate
  return async (values) => schema.getErrors(values)
}

// Prepare the form validation schema.
const SignInFormSchema = new Schema({
  username: {
    type: 'string',
    required: true,
    minLength: 1
  },
  password: {
    type: 'string',
    required: true,
    minLength: 1
  }
})

function SignInForm () {
  const form = useForm({
    initialValues: {
      username: null,
      password: null
    },
    // This function sets the fields props based on a schema.
    initializeField: createFieldInitializer(SignInFormSchema),
    // This function validates all fields (even missing ones) based on a schema.
    validate: createFormValidator(SignInFormSchema),
    // This function validates a single field based on a schema.
    validateField: createFieldValidator(SignInFormSchema),
    onSubmit: async (values) => ({ success: true })
  })
  return (
    <Form context={form}>
      <Field name="username" />
      <FieldError name="username" />

      <Field name="password" />
      <FieldError name="password" />

      <Button type="submit">Sign in</Button>
    </Form>
  )
}

Form component linking

To link and initialize your components with a form instance, use getButtonProps(), getFieldProps() and getFormProps().

import { useFormContext } from '@jalik/react-form'
import { MyCustomButton, MyCustomForm, MyCustomInput } from 'my-custom-ui'

export function FormButton (props) {
  const form = useFormContext()
  return <MyCustomButton {...form.getButtonProps(props)} />
}

export function FormInput (props) {
  const { name } = props
  const form = useFormContext()
  return <MyCustomInput {...form.getFieldProps(name, props)} />
}

export function FormWrapper (props) {
  const form = useFormContext()
  return <MyCustomForm {...form.getFormProps(props)} />
}

Or use the provided components <Button>, <Field> and <Form>.

import { Button, Field, Form } from '@jalik/react-form'
import { MyCustomButton, MyCustomForm, MyCustomInput } from 'my-custom-ui'

export function FormButton (props) {
  return <Button {...props} component={MyCustomButton} />
}

export function FormInput (props) {
  return <Field {...props} component={MyCustomInput} />
}

export function FormWrapper (props) {
  return <Form {...props} component={MyCustomForm} />
}

API

Hooks

useForm (options)

This is where the magic happens, this hook defines the form state and its behavior.

import { useForm } from '@jalik/react-form'

const form = useForm({
  // optional, what to do after a successful submit: 'clear' | 'initialize' | 'reset' | null
  afterSubmit: 'reset',
  // optional, used to debug form
  debug: false,
  // optional, used to disable all fields and buttons
  disabled: false,
  disableOnSubmit: true,
  disableOnValidate: true,
  // optional, disables the submit button if form is not modified
  disableSubmitIfNotModified: false,
  // optional, disables the submit button if form is not valid
  disableSubmitIfNotValid: false,
  // optional, enable native HTML validation on submit
  enableHTMLValidation: false,
  // optional, update form when status changes
  forceUpdateOnStatusChange: false,
  // optional, used to set initial values
  initialValues: undefined,
  // optional, sets initial errors
  initialErrors: {},
  // optional, sets initial modified fields
  initialModified: {},
  // optional, sets initial touched fields
  initialTouched: {},
  // optional, used to replace empty string by null on change and on submit
  nullify: false,
  // optional, prevent native action on submit
  preventDefaultOnSubmit: true,
  // optional, used to initialize form everytime initialValues changes
  reinitialize: false,
  // optional, used to debounce submit
  submitDelay: 100,
  // optional, used to remove extra spaces on blur
  trimOnBlur: false,
  // optional, used to remove extra spaces on submit
  trimOnSubmit: false,
  // optional, used to debounce validation
  validateDelay: 400,
  // optional, used to validate field on change
  validateOnChange: false,
  // optional, used to validate all fields on initialization
  validateOnInit: false,
  // optional, used to validate all fields on submit
  validateOnSubmit: true,
  // optional, used to validate field on touch
  validateOnTouch: false,

  // optional, used to set field props dynamically
  initializeField: (name, formState) => ({
    className: formState.modifiedFields[name] ? 'input-modified' : undefined,
    required: name === 'username'
  }),

  // optional, used to load initial values
  load: async () => ({
    id: 1,
    username: 'test'
  }),

  // REQUIRED, called when form is submitted
  onSubmit: async (values) => ({ success: true }),

  // optional, called when form has been successfully submitted
  onSuccess: (result, values) => {
    // resuls contains the value returned by onSubmit, in this example { success: true }
  },

  // optional, called when form values have changed
  onValuesChange: (values, previousValues) => {
  },

  // optional, called when a field value changed
  // mutation contains all pending changes in a flat object ({field: value})
  // values contains the next form values
  transform: (mutation, values) => {
    // in this example, if lastname or firstname changed,
    // we set the value of "username" like "john.c"
    if (mutation.lastname || mutation.firstname) {
      mutation.username = [
        values.firstname,
        (values.lastname || '')[0]
      ].join('.').toLowerCase()
    }
    return mutation
  },

  // optional, used to validate all fields (expect a promise)
  validate: async (values) => {
    const errors = {}

    if (!values.username) {
      // error can be a string
      errors.username = 'field is required'
      // or an Error
      errors.username = new Error('field is required')
    }
    return errors
  },

  // optional, used to validate a single field (expect a promise)
  validateField: async (name, value, values) => {
    if (name === 'username' && !value) {
      // error can be a string
      return 'field is required'
      // or an Error
      return new Error('field is required')
    }
  }
})

useFormContext ()

This hook returns the form context and functions.

import { useFormContext } from '@jalik/react-form'

const {
  // FORM STATE
  // tells if the form is disabled
  disabled,
  // tells if the form has been initialized
  initialized,
  // tells if the form was modified
  modified,
  // tells if the form was touched
  touched,

  // FORM UTILS
  // returns the button props
  getButtonProps,
  // returns the field props
  getFieldProps,
  // handler for onChange
  handleChange,
  // handler for onBlur
  handleBlur,
  // handler for onReset
  handleReset,
  // handler for onChange((value) => {}) instead of onChange((event) => {})
  handleSetValue,
  // handler for onSubmit
  handleSubmit,

  // LOADING
  load,
  // tells if the form is loading
  loading,
  // loading error (if any)
  loadError,

  // FIELD VALUES
  // clears the form (values, errors...)
  clearValues,
  // returns the field initial value by name
  getInitialValue,
  // returns the field initial value by name
  getValue,
  // initial values (used when form is reset)
  initialValues,
  // removes fields (used for dynamic forms)
  removeValues,
  // resets all or given fields to their initial values
  resetValues,
  // sets the initial values
  setInitialValues,
  // sets value of a field
  setValue,
  // sets values of multiple fields
  setValues,
  // the form values
  values,

  // LIST MANAGEMENT
  appendListItem,
  insertListItem,
  moveListItem,
  prependListItem,
  removeListItem,
  replaceListItem,
  swapListItem,

  // FIELD ERRORS
  // clears all errors
  clearErrors,
  // fields errors
  errors,
  // tells if the form has errors
  hasError,
  // sets a single field error
  setError,
  // sets fields errors
  setErrors,

  // FIELD STATE MANAGEMENT
  // clears all or given fields
  clearModifiedFields,
  // clears all or given fields
  clearTouchedFields,
  // returns the modified fields
  getModifiedFields,
  // returns the touched fields
  getTouchedFields,
  // check if a field was modified
  isModified,
  // check if a field was touched
  isTouched,
  // the list of modified fields
  modifiedFields,
  // resets modified fields to their initial values
  resetModifiedFields,
  // resets touched fields to their initial values
  resetTouchedFields,
  // set a single modified field
  setModifiedField,
  // set all or given modified field
  setModifiedFields,
  // set a single touched field
  setTouchedField,
  // set all or given touched field
  setTouchedFields,
  // the list of touched fields
  touchedFields,

  // FORM SUBMISSION
  // submits the form with values (validate first)
  submit,
  // the number of times the form was submitted.
  // resets to zero when submission succeeds.
  submitCount,
  // the submit error (if any)
  submitError,
  // the submit result (returned by onSubmit)
  submitResult,
  // tells if the form was submitted (changes to false when form is modified)
  submitted,
  // tells if the form is submitting
  submitting,

  // VALIDATION
  // tells if the form will trigger a validation
  // can be a boolean or a list of fields to validate
  needValidation,
  // sets the validation state of the form
  setValidated,
  // sets the validation error
  setValidateError,
  // tells if the form is validating
  setValidating,
  // validates all fields
  validate,
  // the validation error (if any)
  // happens only when an error is thrown during validation
  // it's different from the field validation errors
  validateError,
  // validates given fields
  validateFields,
  // tells if the form was successfully validated
  validated,
  // tells if a field should be validated on change
  validateOnChange,
  // tells if all fields should be validated on initialization
  validateOnInit,
  // tells if all fields should be validated on submit
  validateOnSubmit,
  // tells if a field should be validated on touch
  validateOnTouch,
  // tells if the form is validating
  validating,

  // WATCH
  watch,
  watchers,
} = useFormContext()

useFieldArray (options)

This hook returns utils to manage an array of fields.

import { useFieldArray, useForm } from '@jalik/react-form'

function ItemListForm () {
  const form = useForm({
    initialValues: {
      items: [{ name: 'Item 1' }]
    },
    onSubmit: (values) => Promise.resolve(values)
  })

  const {
    items,
    append,
    prepend,
    remove,
    insert,
    replace,
    move,
    swap,
    handleAppend,
    handlePrepend,
    handleRemove
  } = useFieldArray({
    context: form,
    name: 'items',
    defaultValue: { name: 'New Item' }
  })

  return (
    <div>
      {items.map((item, index) => (
        <div key={item.key}>
          <Field name={item.name} />
          <button type="button" onClick={handleRemove(index)}>Remove</button>
        </div>
      ))}
      <button type="button" onClick={handleAppend}>Add Item</button>
    </div>
  )
}

Components

Some components are provided to ease forms building.

<Button>

This component is synced with the form, so whenever the form is disabled (because it is loading, validating or submitting), the button disabled.

import { Button } from '@jalik/react-form'

function SubmitButton () {
  return (
    <Button type="submit">Submit</Button>
  )
}

<Field>

This component handles the field value and logic.
The name is required.

import { Field } from '@jalik/react-form'
import { Switch } from '@mantine/core'

function parseBoolean (value) {
  return /^true|1$/gi.test(value)
}

export function AcceptTermsField () {
  return (
    <Field
      component={Switch}
      name="acceptTerms"
      parser={parseBoolean}
      type="checkbox"
      value="true"
    />
  )
}

export function CountryField () {
  return (
    <Field
      name="country"
      type="select"
      options={[
        {
          label: 'French Polynesia',
          value: 'pf'
        },
        {
          label: 'New Zealand',
          value: 'nz'
        }
      ]}
    />
  )
}

<FieldError>

This component automatically displays the field error (if any).

import { Field, FieldError } from '@jalik/react-form'

export function PasswordField () {
  return (
    <>
      <Field
        name="password"
        type="password"
      />
      <FieldError name="password" />
    </>
  )
}

<Form>

This component contains the form context, so any component nested in a Form can access the form context using useFormContext().

import { Button, Field, Form, useForm } from '@jalik/react-form'

export function SignInForm () {
  const form = useForm({
    onSubmit: (values) => Promise.resolve(true)
  })
  return (
    <Form context={form}>
      <Field name="username" />
      <Field name="password" />
      <Button type="submit">Sign in</Button>
    </Form>
  )
}

Changelog

History of releases is in the changelog.

License

The code is released under the MIT License.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src		src
test		test
.gitignore		.gitignore
.nvmrc		.nvmrc
.oxlintrc.json		.oxlintrc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

@jalik/react-form

Why using this lib ?

Features

Sandbox

Installing

Creating a form

Loading a form

Loading values inside the form component

Loading values using the `load` option in `useForm()`

Validating a form

Validating using a schema

Form component linking

API

Hooks

useForm (options)

useFormContext ()

useFieldArray (options)

Components

<Button>

<Field>

<FieldError>

<Form>

Changelog

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

@jalik/react-form

Why using this lib ?

Features

Sandbox

Installing

Creating a form

Loading a form

Loading values inside the form component

Loading values using the load option in useForm()

Validating a form

Validating using a schema

Form component linking

API

Hooks

useForm (options)

useFormContext ()

useFieldArray (options)

Components

<Button>

<Field>

<FieldError>

<Form>

Changelog

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Loading values using the `load` option in `useForm()`