@kaliber/forms v2.1.2

Forms

A set of utilities to help you create forms in React.

• Motivation
• Installation
• Usage
• Reference
  • Hooks
  • Schema
  • Validation
  • Components
• Missing feature?
• Other libraries
• Guiding principles
• Disclaimer

Motivation

Creating ad-hoc forms using React hooks is quite easy, but there is one thing that is a bit hard to do: preventing to render the complete form on each keystroke.

Another motivation is to make form handling within our applications more consistent.

Installation

yarn add @kaliber/forms

Usage

Please look at the example for more advanced use-cases.

import { useForm, useFormField } from '@kaliber/forms'
import { required, email } from '@kaliber/forms/validation'

const validationErrors = {
  required: 'This field is required',
  email: 'This is not a valid email',
}

export function Basic() {
  const { form: { fields }, submit } = useForm({
    // provide initial values to populate the form with
    initialValues: {
      name: '',
      email: '',
    },
    // create the form structure, fields are essentially their validation functions
    fields: {
      name: required,
      email: [required, email],
    },
    // handle form submit
    onSubmit: handleSubmit,
  })

  return (
    <form onSubmit={submit}>
      <TextInput label='Name' field={fields.name} />
      <TextInput label='Email' field={fields.email} />
      <button type='submit'>Submit</button>
    </form>
  )

  function handleSubmit(snapshot) {
    // note that the snapshot can still be invalid
    console.log(snapshot)
  }
}

function TextInput({ label, field }) {
  const { name, state, eventHandlers } = useFormField(field)
  const { value = '', error, showError } = state
  return (
    <>
      <div>
        <label htmlFor={name}>{label}</label>
        <input id={name} type='text' {...{ name, value }} {...eventHandlers} />
      </div>
      {showError && <p>{validationErrors[error.id]}</p>}
    </>
  )
}

Reference

See the example for use cases

• Hooks
  • useForm
  • useFormField
  • useNumberFormField
  • useBooleanFormField
  • useArrayFormField
  • useObjectFormField
  • useFormFieldSnapshot
  • useFormFieldValue
  • useFormFieldsValues
• Schema
  • array
  • object
• Validation
• Components
  • FormFieldValue
  • FormFieldsValues
  • FormFieldValid

Hooks

import { ... } from '@kaliber/forms'

useForm

Defines a form.

const {
  form, // 'object' field containing the form
  submit, // handler that can be used to submit the form
  reset, // handler that can be used to reset the form
} = useForm({
  fields, // form structure
  initialValues, // (optional) initial form values
  validate, // (optional) validation for the complete form
  onSubmit, // called when the form is submitted
  formId, // (optional) a custom id, can be useful when multiple forms are placed on the same page
})

useFormField

Subscribes to state changes in the form field and provides the event handlers for form elements.

const {
  name, // the fully qualified name of the form field
  state, // 'object' that contains the form field state
  eventHandlers, // 'object' that contains handlers which can be used by form elements
} = useFormField(field)

useNumberFormField

Specialized version of useFormField that converts the value to a a number if possible.

useBooleanFormField

Specialized version of useFormField that uses the checked state of the event target as value.

useArrayFormField

Subscribes to state changes in the form field and provides helpers for the array field.

const {
  name, // the fully qualified name of the form field
  state, // 'object' that contains the form field state
  helpers, // 'object' that contains handlers that can be used to manipulate the array field
} = useArrayFormField(field)

useObjectFormField

Subscribes to state changes in the form field and provides the fields of the object.

const {
  name, // the fully qualified name of the form field
  state, // 'object' that contains the form field state
  fields, // 'object' containing the fields
} = useObjectFormField(field)

useFormFieldSnapshot

Subscribes to the state of a field (or form).

const snapshot = useFormFieldSnapshot(form)

useFormFieldValue

Subscribes to the value of a field (or form).

const value = useFormFieldValue(field)

useFormFieldsValues

Subscribes to the values of multiple fields (or forms).

const values = useFormFieldsValues(fields)

Schema

import { ... } from '@kaliber/forms'

array

Used to create an array form field.

array(validationOrFields, fields)

Has two signatures:

array(validation, fields)
array(fields)

If you want to use heterogeneous arrays (different types) you can use a function instead of a fields object:

array(initialValue => ({
  _type: required,
  ...(
    initialValue._type === 'content' ? { text: required } :
    initialValue._type === 'image' ? { image: required } :
    null
  )
}))

When rendering the array field you can render a different component based on the value of the field:

const { state: { children }, helpers } = useArrayFormField(field)

return (
  <>
    {children.map(field => {
      const { _type } = field.value.get()
      return (
        _type === 'content' ? <ContentForm key={field.name} {...{ field }} /> :
        _type === 'image' ? <ImageForm key={field.name} {...{ field }} /> :
        null
      )
    })}
    <button type='button' onClick={_ => helpers.add({ _type: 'content' })}>Add content</button>
    <button type='button' onClick={_ => helpers.add({ _type: 'image' })}>Add image</button>
  </>
)

object

Used to create an object form field.

object(validationOrFields, fields)

Has two signatures:

object(validation, fields)
object(fields)

Validation

Validation functions have this shape: (value, { form, parents }) => falsy | { id, params }

We provide a few commonly used validation functions.

import { ... } from '@kaliber/forms/validation'

Components

When you want to conditionally render or set some props based on your current form state, you should avoid the use of useFormFieldSnapshot or useFormFieldValue in your form root, since that will re-render your entire form with each change. Rather you should create a specialised component and make the values available through a render prop.

Because this is such a common usecase, we provide several of these components.

FormFieldValue

Example

<FormFieldValue field={fields.subscribeToNewsletter} render={value => (
  value && <TextInput label='Email' field={fields.email} />
)}>

FormFieldsValues

Example

<FormFieldValue field={[fields.firstName, fields.lastName]} render={([firstName, lastName]) => (
  firstName && lastName && <Greeting>{firstName} {lastName}</Greeting>
)}>

FormFieldValid

Example

<FormFieldValid field={form} render={valid => (
  <Button type="submit" disabled={!valid}>Verstuur</Button>
)}>

Missing feature?

If the library has a constraint that prevents you from implementing a specific feature (outside of the library) start a conversation.

If you think a feature should be added to the library because it solves a specific use case, discuss it to determine if the complexity of introducing it is worth it.

Other libraries

Existing libraries have one or more of the following problems:

• Too big / too complex
• Not following the React philosophy
• Too much boilerplate for simple forms
• Validation results are
  • hard to translate
  • difficult to use in combination with accessibility principles
• Different guiding principles and trade-offs

Guiding principles

• Static form structure
• No visual components
• Clean DSL for creating the form structure
• No async validation
• Minimal / small
• Translatable validation results
• Conscious complexity / usefulness / commonality trade-offs

Disclaimer

This library is intended for internal use, we provide no support, use at your own risk. It does not import React, but expects it to be provided, which @kaliber/build can handle for you.

This library is not transpiled.