Formikate

Lightweight form builder for React that lets you dynamically render form fields from validation schemas, manage multi-step flows, and simplify validation handling.

View Live Demo →

Contents

1. Features
2. Getting started
3. Fields
4. Status
5. Rendering
6. Multi-step
7. Empty state

Features

• Dynamically render form fields using zod validation schemas
• Declarative multi-step forms via useFields configuration
• Fields can be marked excluded: true to be left out of the form and reset to their initial values
• Included fields with hidden: true are validated on submit but never rendered — surfaced through onInvalid (which fires on any submit-blocked validation and passes meta.hidden to identify this case)
• Steps whose included fields are all hidden (or whose fields are all excluded) are automatically skipped during navigation
• Per-step validation — only fields on the current step (or earlier) are validated on submit

Getting started

Begin by defining your validation schema and field descriptors:

import * as z from 'zod';

export const schema = z.object({
    name: z.string().min(1, 'Name is required'),
    address: z.string().min(1, 'Address is required'),
    guest: z.boolean(),
});

export type Schema = z.infer<typeof schema>;

export const fields = {
    name: {
        step: 'personal' as const,
        validate: schema.shape.name,
        initial: '',
    },
    address: {
        step: 'delivery' as const,
        validate: schema.shape.address,
        initial: '',
    },
    guest: {
        step: 'personal' as const,
        validate: schema.shape.guest,
        initial: false,
    },
};

Import useForm – it accepts all of the same useFormik (Formik) arguments (except validate, validationSchema, and initialValues which are handled internally). Initial values are derived from each field's initial property:

import { useForm, useFields, Cursor } from 'formikate';
import { fields } from './utils';

const form = useForm<Schema>({
    fields,
    validateOnBlur: false,
    validateOnChange: false,
    onSubmit(values) {
        if (!form.status.progress.last())
            return void form.status.navigate.to(Cursor.Next);
        console.log('Submitting', values);
    },
});

You can use form to access all of the usual Formik properties such as form.values and form.errors.

Fields

Use useFields to declare the step structure and field configuration. The step property on each field is strongly typed — it must match one of the identifiers in the steps array:

useFields(form, () => ({
    steps: ['personal', 'delivery', 'review'],
    fields: {
        ...fields,
        address: {
            ...fields.address,
            excluded: form.values.guest,
        },
    },
}));

Config

| Property | Type | Description | | -------- | -------------------------------- | ----------------------------------------- | | steps | (string \| number \| symbol)[] | Ordered list of step identifiers | | fields | Record<string, FieldConfig> | Map of field names to their configuration |

Field config

| Property | Type | Description | | ---------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | step | string \| number \| symbol | Which step this field belongs to — must match one of the identifiers in steps | | validate | ZodType | Zod schema used for validation | | initial | z.infer<validate> \| null \| undefined | Initial value — typed from the validate schema; also the reset value when excluded | | excluded | boolean? | When true, the field is left out of the form — not validated, not rendered, and reset to initial. Defaults to false | | hidden | boolean? | When true on an included field, the field is not rendered but its value is still submitted and validated on every submit attempt. Ignored when excluded. onInvalid fires on any submit-blocked validation and sets meta.hidden = true when at least one invalid field is hidden |

Step state derivation

A step's inclusion and visibility are derived from its fields:

• Any included field (or zero fields) → step is .included(). It appears in the navigation flow when at least one field is non-hidden.
• Every included field on the step is hidden: true → the step is included but .hidden(). It is skipped in navigation; its fields still validate on submit.
• Every field is excluded: true → step is .excluded(). It is fully absent.

Skipping

Steps whose included fields are all hidden, or whose fields are all excluded, are skipped during navigation:

useFields(form, () => ({
    steps: ['personal', 'delivery', 'review'],
    fields: {
        ...fields,
        address: {
            ...fields.address,
            excluded: form.values.guest,
        },
    },
}));

When guest is true, the address field becomes excluded, so the delivery step (whose only field is now absent) is skipped.

Status

After calling useFields, the computed state is available on form.status. All accessors are functions for consistency:

form.status.empty; // boolean — true when no fields/steps are configured
form.status.field; // Record<string, Result>
form.status.step; // Record<Step, StepResult>
form.status.progress; // step progression
form.status.navigate; // navigation controls

Field state

form.status.field.name.included(); // true when the field is in the form
form.status.field.name.excluded(); // true when the field is excluded
form.status.field.name.hidden(); // true when included but flagged hidden
form.status.field.name.visible(); // true when included and not hidden (i.e. should render)
form.status.field.name.required(); // true if the Zod schema rejects `undefined`
form.status.field.name.optional(); // inverse of required()

Step state

form.status.step.personal.included(); // true when this step is in the navigation flow
form.status.step.personal.excluded(); // true when the step is fully absent
form.status.step.personal.hidden(); // true when every included field is hidden
form.status.step.personal.visible(); // true when the step has at least one non-hidden field
form.status.step.personal.active(); // true when this is the current step
form.status.step.personal.fields(); // array of visible included field names on this step

Progress

form.status.progress.current(); // identifier of the current step
form.status.progress.position(); // zero-based index within visible steps
form.status.progress.total(); // total number of visible steps
form.status.progress.first(); // whether on the first visible step
form.status.progress.last(); // whether on the last visible step
form.status.progress.steps(); // array of { id, index } for visible steps

Navigation

import { Cursor } from 'formikate';

form.status.navigate.to(Cursor.Next); // go to next step
form.status.navigate.to(Cursor.Previous); // go to previous step
form.status.navigate.to(Cursor.First); // jump to first step
form.status.navigate.to(Cursor.Last); // jump to last step
form.status.navigate.to('review'); // go to a specific step by id

form.status.navigate.possible(Cursor.Next); // true if a next step exists
form.status.navigate.possible(Cursor.Previous); // true if a previous step exists
form.status.navigate.possible(Cursor.First); // true if a first step exists
form.status.navigate.possible(Cursor.Last); // true if a last step exists
form.status.navigate.possible('review'); // true if a specific step is reachable

Rendering

Use Formikate's Form component to provide the form to child components:

import { Form, Cursor } from 'formikate';

<Form value={form}>
    <form onSubmit={form.handleSubmit}>
        {form.status.field.name.visible() && (
            <input type="text" {...form.getFieldProps('name')} />
        )}

        {form.status.field.address.visible() && (
            <input type="text" {...form.getFieldProps('address')} />
        )}

        <button
            type="button"
            disabled={!form.status.navigate.possible(Cursor.Previous)}
            onClick={() => form.status.navigate.to(Cursor.Previous)}
        >
            Back
        </button>

        <button type="submit">
            {form.status.progress.last() ? 'Submit' : 'Next'}
        </button>
    </form>
</Form>;

Child components

Use the useFormContext hook in child components to access the form with properly typed status:

import { useFormContext } from 'formikate';
import type { Schema } from './types';

function NameField() {
    const form = useFormContext<Schema>();

    if (!form.status.field.name.visible()) return null;

    return <input type="text" {...form.getFieldProps('name')} />;
}

Multi-step

Gate whole sections of your form by step using form.status.step[id].active(). Each step renders only when it's the current step:

import { Form, Cursor } from 'formikate';

<Form value={form}>
    <form onSubmit={form.handleSubmit}>
        {form.status.step.personal.active() && (
            <>
                <input type="text" {...form.getFieldProps('name')} />
                <input type="checkbox" {...form.getFieldProps('guest')} />
            </>
        )}

        {form.status.step.delivery.active() && (
            <input type="text" {...form.getFieldProps('address')} />
        )}

        {form.status.step.review.active() && <Review />}

        <button
            type="button"
            disabled={!form.status.navigate.possible(Cursor.Previous)}
            onClick={() => form.status.navigate.to(Cursor.Previous)}
        >
            Back
        </button>

        <button type="submit">
            {form.status.progress.last() ? 'Submit' : 'Next'}
        </button>
    </form>
</Form>;

Advance steps from inside onSubmit — per-step validation runs first, so the call only fires once the current step is valid:

const form = useForm<Schema>({
    fields,
    onSubmit(values) {
        if (!form.status.progress.last())
            return void form.status.navigate.to(Cursor.Next);
        console.log('Submitting', values);
    },
});

For milestone steps that have no inputs (e.g. a "done" screen), check step[id].fields().length === 0 to swap the Next button for a different action:

{
    form.status.step.done.active() &&
        form.status.step.done.fields().length === 0 && <Done />;
}

Empty state

When no fields or steps are configured, form.status.empty is true:

{
    form.status.empty ? (
        <p>No fields available</p>
    ) : (
        <form onSubmit={form.handleSubmit}>{/* ... */}</form>
    );
}