Overview

Crustack Form is a simple and flexible solution for building accessible forms. It is TypeScript-first and fully headless, giving you complete control over your UI.

Installation

npm install @crustack/form

Motivation

Many existing form solutions overlook accessibility, prioritizing only state management. Crustack Form, however, places accessibility as its primary focus.

Comprehensive type safety is a fundamental requirement. Every aspect of the form, from hooks to components, is designed to be strictly type-safe, addressing the often loose typing found in other libraries.

Crustack Form also aims to streamline the form validation process. While other solutions may offer numerous, sometimes confusing, validation methods, Crustack Form provides a straightforward and non-redundant approach.

Show me some code!

Let's build a basic form that demonstrates key features of Crustack Form. The form contains two fields - title and description. Each field includes:

A label for accessibility
A descriptive helper text
An input control with validation
Error message display

The form also showcases:

Real-time validation feedback
Error summary with quick navigation
Success/failure submission states

Here's the code:

import { defineForm } from '@crustack/form'

type FormValues = { title: string; description: string }
type SubmissionError = string
type SubmissionData = string

const form = defineForm<FormValues, SubmissionError, SubmissionData>()

function TodoForm() {
  return (
    <form.Root
      initialValues={{ title: '', description: '' }}
      onSubmit={(values) =>
        Math.random() > 0.5
          ? Promise.resolve('Form submitted succesfully')
          : Promise.reject('Something went wrong')
      }
    >
      {(ctx) => (
        <form.Form>
          <form.Field
            name="title"
            validate={(title) => title.length < 5 && 'Too short'}
          >
            <form.Label children="Title" />
            <form.Description children="Add a title to your new todo" />
            <form.Control>
              <input
                value={ctx.getFieldValue('title')}
                onChange={(e) => ctx.setFieldValue('title', e.target.value)}
                onBlur={() => ctx.setFieldTouched('title', true)}
              />
            </form.Control>
            <form.ErrorMessage />
          </form.Field>

          <form.Field
            name="description"
            validate={(title) => title.length < 20 && 'Too short'}
          >
            <form.Label children="Description" />
            <form.Description children="The description of your new todo" />
            <form.Control>
              <input
                value={ctx.getFieldValue('description')}
                onChange={(e) =>
                  ctx.setFieldValue('description', e.target.value)
                }
                onBlur={() => ctx.setFieldTouched('description', true)}
              />
            </form.Control>
            <form.ErrorMessage />
          </form.Field>

          {/* The submission state depends on `<form.Root onSubmit={...} />` */}
          {/* Its type has been defined upfront on `defineForm` */}
          {ctx.submission.isError && <div>{ctx.submission.error}</div>}
          {ctx.submission.isSuccess && <div>{ctx.submission.data}</div>}

          {/* Show the error count after a failed submit attempt */}
          {!!ctx.hasErrors && !!ctx.submission.attempt && (
            <div>
              The form has {ctx.errorCount.all} error(s)&nbsp;
              {/* Add a button to go to the first error */}
              <button
                children="See the error"
                onClick={() => ctx.scrollToFirstTouchedError()}
              />
            </div>
          )}
          <button children="Submit" disabled={ctx.submission.isLoading} />
        </form.Form>
      )}
    </form.Root>
  )
}

Overview

Installation

Motivation

Show me some code!

On this page