Browse docs

API Reference

Complete reference for Form System APIs.

DashForm

The DashForm component wraps your form and provides the reactive engine, reactions, and runtime store.

tsx

import { DashForm } from '@dashforge/forms';

<DashForm
  reactions={reactions}
  defaultValues={{ country: 'United States' }}
  onSubmit={(data) => console.log(data)}
>
  {/* form fields */}
</DashForm>

Prop	Type	Default	Description
`reactions`	`ReactionDefinition[]`	`[]`	Array of reaction definitions for dynamic behavior
`resolver`	`Resolver<FormValues>`	—	Optional schema-based validation resolver (Zod, Yup, Joi, etc.)
`onSubmit`	`(data: FormValues) => void \| Promise<void>`	required	Form submission handler
`defaultValues`	`Partial<FormValues>`	—	Initial form values
`children`	`React.ReactNode`	required	Form fields and content

Schema-Based Validation (Resolver)

Architectural note: Dashforge does NOT bundle or provide validation logic. The resolver is a pure pass-through to React Hook Form. Users must install and configure their own validation library such as Zod, Yup, Joi, Valibot, or ArkType.

The resolver prop accepts a React Hook Form resolver function. Resolvers translate validation schemas into error objects. This enables schema-based validation instead of field-level rules.

Approach	Prop	Description
Field Rules	`rules` prop	Simple field-level validation (required, min, max, pattern)
Resolver	`resolver` prop	Schema-based validation with type safety and reusable schemas
Reactions	`reactions` array	Dynamic cross-field validation triggered by value changes

With Zod

bash

npm install zod @hookform/resolvers

tsx

import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { DashForm } from '@dashforge/forms';
import { TextField, NumberField } from '@dashforge/tw';

const schema = z.object({
  email: z.string().email('Invalid email address'),
  age: z.number().min(18, 'Must be at least 18'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

type FormValues = z.infer<typeof schema>;

function RegistrationForm() {
  const handleSubmit = (data: FormValues) => {
    console.log('Valid data:', data);
  };

  return (
    <DashForm
      resolver={zodResolver(schema)}
      defaultValues={{ email: '', age: 0, password: '' }}
      onSubmit={handleSubmit}
    >
      <TextField name="email" label="Email" />
      <NumberField name="age" label="Age" />
      <TextField name="password" label="Password" type="password" />
    </DashForm>
  );
}

Here is a live, runnable version — blur a field empty or invalid to see the Zod messages surface through the normal Dashforge error path. Use the StackBlitz button on the preview toolbar to open it as a full project:

import { DashForm } from '@dashforge/forms';
import { TextField, Box, Stack, Button } from '@dashforge/tw';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// Dashforge does NOT bundle a validation library.
// Install your own: npm install zod @hookform/resolvers
const schema = z.object({
  email: z
    .string()
    .min(1, 'Email is required')
    .email('Enter a valid email address'),
  age: z
    .string()
    .min(1, 'Age is required')
    .refine((v) => Number(v) >= 18, 'You must be 18 or older'),
});

type SignupForm = z.infer<typeof schema>;

export function SignupForm() {
  return (
    <Box sx="w-full max-w-md">
      <DashForm<SignupForm>
        resolver={zodResolver(schema)}
        defaultValues={{ email: '', age: '' }}
        mode="onBlur"
        onSubmit={(data) => console.log('Valid!', data)}
      >
        <Stack gap={2}>
          <TextField name="email" label="Email" fullWidth />
          <TextField name="age" label="Age" fullWidth />
          <Button type="submit" variant="solid" sx="self-start">
            Submit
          </Button>
        </Stack>
      </DashForm>
    </Box>
  );
}

The schema above uses z.coerce.number() for brevity. In the live demo both fields are typed as string and age is range-checked with .refine() — this keeps the schema's input and output types identical, which is what DashForm's resolver prop expects. Reach for z.coerce only when you handle the input/output type split yourself.

With Yup

bash

npm install yup @hookform/resolvers

tsx

import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from 'yup';
import { DashForm } from '@dashforge/forms';
import { TextField } from '@dashforge/tw';

const schema = yup.object({
  email: yup.string().email('Invalid email').required('Email is required'),
  password: yup.string().min(8, 'Password too short').required('Required'),
});

function LoginForm() {
  return (
    <DashForm
      resolver={yupResolver(schema)}
      defaultValues={{ email: '', password: '' }}
      onSubmit={(data) => console.log(data)}
    >
      <TextField name="email" label="Email" />
      <TextField name="password" label="Password" type="password" />
    </DashForm>
  );
}

Validation flow: When a resolver is provided, it becomes the primary validation source. Errors still flow through bridge.getError() and display automatically in Dashforge UI components. Error gating, touch tracking, and all other features work normally.

When to Use Resolver

✅ Validation schema is reused across forms
✅ Validation logic is complex (cross-field, conditional)
✅ Type safety with schema inference is required
✅ Team already uses Zod/Yup

When to Use Field Rules

✅ Validation is simple (required, min, max, pattern)
✅ Each field has independent validation
✅ No schema library is needed

ReactionDefinition

Reactions are defined as objects with these properties:

Prop	Type	Default	Description
`id`	`string`	required	Unique identifier
`watch`	`string[]`	required	Field names to watch
`when`	`(ctx: WhenContext) => boolean`	—	Optional condition
`run`	`(ctx: RunContext) => void \| Promise<void>`	required	Effect to execute

RunContext

The run context provides methods for reading/writing form state:

Method	Type	Description
`getValue<T>(name)`	`(name: string) => T`	Read field value
`setValue(name, value)`	`(name: string, value: unknown) => void`	Update field value
`getRuntime<TData>(name)`	`(name: string) => FieldRuntimeState<TData>`	Read runtime state
`setRuntime<TData>(name, patch)`	`(name: string, patch: Partial<FieldRuntimeState<TData>>) => void`	Update runtime state
`beginAsync(key)`	`(key: string) => number`	Start async operation
`isLatest(key, id)`	`(key: string, requestId: number) => boolean`	Check if response is valid

FieldRuntimeState

Runtime state stores async metadata separate from form values:

tsx

interface FieldRuntimeState<TData = unknown> {
  status: 'idle' | 'loading' | 'ready' | 'error';
  data: TData | null;
  error: string | null;
}

Prop	Type	Default	Description
`status`	`'idle' \| 'loading' \| 'ready' \| 'error'`	`'idle'`	Current operation status
`data`	`TData \| null`	`null`	Runtime data (e.g., options)
`error`	`string \| null`	`null`	Error message if status is `'error'`

visibleWhen

All form components accept a visibleWhen prop for conditional rendering:

tsx

visibleWhen?: (engine: Engine) => boolean

// Example
<TextField
  name="companyName"
  label="Company Name"
  visibleWhen={(engine) => 
    engine.getNode('accountType')?.value === 'business'
  }
/>

optionsFromFieldData

Select and Autocomplete components can load options from runtime state:

tsx

<Select
  name="state"
  label="State"
  optionsFromFieldData
/>

// Runtime state structure expected:
{
  status: 'ready',
  data: {
    options: ['California', 'Texas', 'New York']
  }
}