Powerful form management with Zustand and Zod validation

Zustorm combines the simplicity of Zustand with the power of Zod validation to create a type-safe, intuitive form management solution for React applications.

Features

• Simple & Intuitive - Familiar Zustand patterns for form state
• Type Safe - Full TypeScript support with automatic type inference
• Built-in Validation - Seamless Zod schema integration
• High Performance - Granular updates and minimal re-renders
• Flexible Architecture - Global stores or React Context patterns
• Zero Dependencies - Only peer deps: Zustand, Zod, and React

Installation

npm install zustorm zustand zod react

Quick Start

import { z } from 'zod';
import { create } from 'zustand';
import { withForm, getDefaultForm, FormController } from 'zustorm';

type UserForm = {
  name: string;
  email: string;
};

const useUserForm = create(
  withForm(() => getDefaultForm<UserForm>({ name: '', email: '' }), {
    getSchema: () =>
      z.object({
        name: z.string().min(1, 'Name required'),
        email: z.string().email('Invalid email'),
      }),
  })
);

function UserForm() {
  const isValid = useUserForm((state) => !state.errors);
  const isDirty = useUserForm((state) => state.dirty);

  return (
    <form>
      <FormController
        store={useUserForm}
        name="name"
        render={({ value, onChange, error }) => (
          <input value={value} onChange={(e) => onChange(e.target.value)} />
        )}
      />
      <FormController
        store={useUserForm}
        name="email"
        render={({ value, onChange, error }) => (
          <input value={value} onChange={(e) => onChange(e.target.value)} />
        )}
      />
      <button disabled={!isValid || !isDirty}>Submit</button>
    </form>
  );
}

Using Form Provider

import { useMemo } from 'react';
import { FormStoreProvider, useFormStore, FormController } from 'zustorm';

function App() {
  ...
  return (
    <FormStoreProvider store={store}>
      <UserForm />
    </FormStoreProvider>
  );
}

function UserForm() {
  const store = useFormStore();
  return (
    <FormController
      store={store}
      name="name"
      render={({ value, onChange }) => (
        <input value={value} onChange={(e) => onChange(e.target.value)} />
      )}
    />
  );
}

FormStoreProvider also takes in an optional options.name to scope the form.

Dynamic Arrays

<FormController
  name="friends"
  render={({ value, onChange }) => (
    <div>
      {value.map((_, index) => (
        <FormController
          key={index}
          store={store}
          name={`friends.${index}.name`}
          render={({ value, onChange }) => (
            <input value={value} onChange={(e) => onChange(e.target.value)} />
          )}
        />
      ))}
      <button onClick={() => onChange([...value, { name: '' }])}>
        Add Friend
      </button>
    </div>
  )}
/>

FormController ContextSelector

The FormController also has a contextSelector prop to access the form store values. This is useful for accessing the form state without needing to cause re-renders for every field.

<FormController
  store={store}
  name="email"
  contextSelector={(values) => values.name}
  render={({ value, onChange, error, context }) => (
    <input
      value={value}
      onChange={(e) => onChange(e.target.value)}
      placeholder={`Hello ${context}`}
    />
  )}
/>

Please note that contextSelector uses options.useStore internally, so this can be optimized further if needed.

⚠️ Important: When using contextSelector, ensure the selected context value is stable to avoid unnecessary re-renders (or "Maximum update depth exceeded" errors in Zustand v5). Use stable selector functions or pass useStoreWithEqualityFn into the options prop of FormController.

Using Form Store Directly

You can also use the form store directly without the FormController for granular control over rendering and state management. This is not recommended for most cases, but can be useful for advanced scenarios.

import { useFormStore } from 'zustorm';
import { useEffect } from 'react';
import { useStore } from 'zustand';

function UserForm() {
  const store = useFormStore();

  const name = useStore(store, (state) => state.values.name);
  const updateName = (newName: string) => {
    store.setState((state) => ({
      ...state,
      values: { ...state.values, name: newName },
    }));
  };

  return (
    <div>
      <input value={name} onChange={(e) => updateName(e.target.value)} />
      <button type="submit">Submit</button>
    </div>
  );
}

Performance

Zustorm allows all the flexiblity of Zustand's performance optimizations. This means you can use useStore or useStoreWithEqualityFn or any other hook you'd like to optimize your form state access.

Here is how it is done with the FormController:

<FormController
  ...
  options={{
    useStore: (api, selector) =>
      useStoreWithEqualityFn(api, selector, (a, b) => a === b),
  }}
/>

API

| Function | Description | | ----------------------------- | ---------------------------------------------- | | withForm(creator, options) | Enhances Zustand store with form capabilities | | FormController | Renders form fields with state binding | | FormStoreProvider | Provides form store context | | useFormStore() | Access form store from context | | getDefaultForm(values) | Returns default form state | | getFormApi(store, formPath) | Access deep form API methods | | createFormStoreProvider() | Creates a FormStoreProvider component and hook |

Examples

Complete examples with styling and advanced features:

• Global Store Example
• Context Example
• Array Handling Example

TypeScript Compatibility

This package's type definitions require TypeScript 5.0 or higher due to the use of const type parameters and other advanced type features.

Make sure you're using TypeScript 5.0+ to take full advantage of type safety and autocomplete.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.