{props.label} {props.required && *} {props.multiline ? (

) : (
            <input {...inputProps} type={props.type || 'text'} />
          )}
          
          {error && (
            <p className="text-sm text-red-600">{error[0].message}</p>
          )}
        </div>
      );
    };
    ```

Now let's configure RilayKit with our renderer:

```tsx title="lib/rilay.ts"
    import { ril } from 'rilaykit';
    import { InputRenderer } from './components';

// Create and configure the RilayKit instance
    export const rilay = ril
      .create()
      .addComponent('input', {
        name: 'Input Field',
        renderer: InputRenderer,
        defaultProps: { 
          label: 'Input Field', 
          placeholder: 'Enter value...',
          type: 'text'
        }
      });
    ```
  </Step>

<Step>
    2. Build the Form Configuration [#2-build-the-form-configuration]

Now we'll use RilayKit's **fluent API** to build our form. This declarative approach makes forms easy to read and modify.

```tsx title="lib/contactForm.ts"
    import { required, email, minLength, when } from 'rilaykit';
    import { rilay } from './rilay';

export const contactForm = rilay
      .form('contact-us') // Unique form ID
      .add({
        id: 'name',
        type: 'input',
        props: {
          label: 'Full Name',
          placeholder: 'Enter your full name',
          required: true,
          type: 'text'
        },
        validation: {
          validate: [
            required('Name is required'),
            minLength(2, 'Name must be at least 2 characters')
          ]
        }
      })
      .add({
        id: 'email',
        type: 'input',
        props: {
          label: 'Email Address',
          placeholder: 'Enter your email address',
          required: true,
          type: 'email'
        },
        validation: {
          validate: [
            required('Email is required'),
            email('Please enter a valid email address')
          ]
        }
      })
      .add({
        id: 'message',
        type: 'input',
        props: {
          label: 'Your Message',
          placeholder: 'Tell us what\'s on your mind...',
          required: true,
          multiline: true,
          rows: 4
        },
        validation: {
          validate: [
            required('Message is required'),
            minLength(10, 'Message must be at least 10 characters')
          ]
        },
        conditions: {
          visible: when('email').exists() // Only show after email is entered
        }
      })
      .build();
    ```

<Callout type="info">
      **Key concepts:**

* `validation`: Object with a `validate` array of Standard Schema validators
      * `conditions`: Control when fields are visible or enabled
      * `props`: Custom properties passed to your renderer component
    </Callout>
  </Step>

<Step>
    3. Render the Form [#3-render-the-form]

Finally, let's create a React component that renders our form using RilayKit's `<Form>` and `<FormField>` components.

```tsx title="components/ContactForm.tsx"
    import React from 'react';
    import { Form, FormField } from 'rilaykit';
    import { contactForm } from '@/lib/contactForm';

export function ContactForm() {
      const handleSubmit = (data: { name: string; email: string; message: string }) => {
        // Handle form submission - send to API, show success message, etc.
        alert(`Thank you, ${data.name}! Your message has been received.`);
        console.log('Form data:', data);
      };

return (
        <div className="max-w-md mx-auto bg-white shadow-lg rounded-lg p-6">
          <h2 className="text-2xl font-bold text-gray-900 mb-6">Contact Us</h2>
          
          <Form
            formConfig={contactForm}
            onSubmit={handleSubmit}
            defaultValues={{ name: '', email: '', message: '' }}
            className="space-y-4"
          >
            <FormField fieldId="name" />
            <FormField fieldId="email" />
            <FormField fieldId="message" />
            
            <button 
              type="submit"
              className="w-full bg-blue-600 hover:bg-blue-700 text-white font-medium py-2 px-4 rounded-md transition-colors"
            >
              Send Message
            </button>
          </Form>
        </div>
      );
    }
    ```

Use it anywhere in your app:

```tsx title="pages/contact.tsx"
    import { ContactForm } from '@/components/ContactForm';

export default function ContactPage() {
      return (
        <div className="min-h-screen bg-gray-50 py-12">
          <div className="container mx-auto px-4">
            <ContactForm />
          </div>
        </div>
      );
    }
    ```
  </Step>
</Steps>

Congratulations [#congratulations]

You've built a complete contact form with RilayKit. Here's what you accomplished:

* Created reusable component renderers that work with any UI library
* Built a type-safe form with intelligent autocompletion
* Added real-time validation with custom error messages
* Implemented conditional logic (message field appears after email)
* Handled form submission with properly typed data

Next Steps [#next-steps]

Now that you understand the basics, explore more advanced features:

* **[Examples Gallery](/examples)** - See RilayKit with different UI libraries
* **[Advanced Forms](/forms/advanced-forms)** - Learn about dynamic fields, async validation, and complex conditions
* **[Multi-Step Workflows](/workflow/building-workflows)** - Create onboarding flows and wizards
* **[Validation](/core-concepts/validation)** - Standard Schema support for Zod, Yup, Joi and more

Common Questions [#common-questions]

<details>
  <summary>
    **How do I style the form differently?**
  </summary>

Update your component renderers with different CSS classes or use CSS-in-JS libraries. RilayKit is completely UI-agnostic.
</details>

<details>
  <summary>
    **Can I use this with Material-UI/Chakra/Ant Design?**
  </summary>

Absolutely! Check our [Examples Gallery](/examples) for integration examples with popular UI libraries.
</details>

<details>
  <summary>
    **How do I add more validation rules?**
  </summary>

RilayKit includes many built-in validators, or you can create custom ones. See [Validation Guide](/forms/validation) for details.
</details>

<details>
  <summary>
    **Is this production-ready?**
  </summary>

Yes! RilayKit is built for production use with full TypeScript support, comprehensive testing, and performance optimizations.
</details>

# Accessibility

import { Callout } from 'fumadocs-ui/components/callout';

Accessibility in a Headless Library [#accessibility-in-a-headless-library]

<Callout type="warn">
  RilayKit is fully headless -- it manages form state and logic, but generates no HTML. This means accessibility is your responsibility. The patterns below will help you build WCAG 2.1 AA compliant forms using RilayKit's renderer system.
</Callout>

This is intentional, and it works in your favor.

Libraries that generate HTML often inject their own ARIA attributes, sometimes incorrectly. They make assumptions about your markup structure, your error display strategy, and your focus management approach. When those assumptions conflict with your design system, you end up fighting the library.

RilayKit sidesteps this entirely. Because it produces zero HTML and zero ARIA attributes, there are no conflicting assumptions. You control every element, every attribute, and every interaction. The trade-off is that you must implement accessibility yourself -- but you get to do it correctly for your specific context.

The renderer system provides all the data you need to build accessible components: `id` for label association, `error` for validation state, `disabled` for interaction state, `touched` for display logic, and `onBlur` for focus tracking.

Building Accessible Renderers [#building-accessible-renderers]

Every `ComponentRenderer` receives a `ComponentRenderProps` object with the following properties:

* `id` -- Unique field identifier, use it for `htmlFor`/`id` pairing
* `props` -- Your component-specific props (label, placeholder, etc.)
* `value` -- Current field value
* `onChange` -- Value change handler
* `onBlur` -- Blur handler for touch tracking
* `disabled` -- Whether the field is disabled
* `error` -- Array of `ValidationError` objects (each has a `message` property)
* `isValidating` -- Whether async validation is in progress
* `touched` -- Whether the field has been interacted with

Here is a fully accessible input renderer:

```tsx title="components/accessible-input.tsx"
import type { ComponentRenderer } from '@rilaykit/core';

interface InputProps {
  label: string;
  type?: string;
  placeholder?: string;
  helpText?: string;
  required?: boolean;
}

const AccessibleInput: ComponentRenderer<InputProps> = ({
  id, value, onChange, onBlur, error, disabled, touched, props
}) => {
  const errorId = `${id}-error`;
  const helpId = `${id}-help`;
  const hasError = touched && error && error.length > 0;

return (
    <div>
      <label htmlFor={id}>
        {props.label}
        {props.required && <span aria-hidden="true"> *</span>}
      </label>
      <input
        id={id}
        type={props.type || 'text'}
        value={value || ''}
        onChange={(e) => onChange?.(e.target.value)}
        onBlur={onBlur}
        disabled={disabled}
        placeholder={props.placeholder}
        aria-invalid={hasError ? 'true' : undefined}
        aria-describedby={[
          hasError ? errorId : null,
          props.helpText ? helpId : null,
        ].filter(Boolean).join(' ') || undefined}
        aria-required={props.required || undefined}
      />
      {props.helpText && (
        <p id={helpId}>{props.helpText}</p>
      )}
      {hasError && (
        <p id={errorId} role="alert">
          {error[0].message}
        </p>
      )}
    </div>
  );
};
```

Key points in this implementation:

* The `label` element is linked to the input via `htmlFor={id}` and the input's `id` attribute. This is the most important accessibility requirement for form fields.
* `aria-invalid` is only set when the field has been touched and has errors. Setting it before the user interacts with the field creates a confusing experience.
* `aria-describedby` links the input to both the help text and the error message. When both exist, screen readers announce them in order.
* `aria-required` communicates the requirement to assistive technology, while the visual `*` indicator (hidden from screen readers with `aria-hidden`) communicates it visually.
* The error message uses `role="alert"`, which causes screen readers to announce it immediately when it appears.

Select and Checkbox Patterns [#select-and-checkbox-patterns]

Accessible Select [#accessible-select]

```tsx title="components/accessible-select.tsx"
import type { ComponentRenderer } from '@rilaykit/core';

interface SelectProps {
  label: string;
  options: { value: string; label: string }[];
  placeholder?: string;
  helpText?: string;
  required?: boolean;
}

const AccessibleSelect: ComponentRenderer<SelectProps> = ({
  id, value, onChange, onBlur, error, disabled, touched, props
}) => {
  const errorId = `${id}-error`;
  const helpId = `${id}-help`;
  const hasError = touched && error && error.length > 0;

return (
    <div>
      <label htmlFor={id}>
        {props.label}
        {props.required && <span aria-hidden="true"> *</span>}
      </label>
      <select
        id={id}
        value={value || ''}
        onChange={(e) => onChange?.(e.target.value)}
        onBlur={onBlur}
        disabled={disabled}
        aria-invalid={hasError ? 'true' : undefined}
        aria-describedby={[
          hasError ? errorId : null,
          props.helpText ? helpId : null,
        ].filter(Boolean).join(' ') || undefined}
        aria-required={props.required || undefined}
      >
        {props.placeholder && (
          <option value="" disabled>
            {props.placeholder}
          </option>
        )}
        {props.options.map((option) => (
          <option key={option.value} value={option.value}>
            {option.label}
          </option>
        ))}
      </select>
      {props.helpText && (
        <p id={helpId}>{props.helpText}</p>
      )}
      {hasError && (
        <p id={errorId} role="alert">
          {error[0].message}
        </p>
      )}
    </div>
  );
};
```

Accessible Checkbox [#accessible-checkbox]

```tsx title="components/accessible-checkbox.tsx"
import type { ComponentRenderer } from '@rilaykit/core';

interface CheckboxProps {
  label: string;
  helpText?: string;
  required?: boolean;
}

const AccessibleCheckbox: ComponentRenderer<CheckboxProps> = ({
  id, value, onChange, onBlur, error, disabled, touched, props
}) => {
  const errorId = `${id}-error`;
  const helpId = `${id}-help`;
  const hasError = touched && error && error.length > 0;

return (
    <div>
      <label>
        <input
          id={id}
          type="checkbox"
          checked={Boolean(value)}
          onChange={(e) => onChange?.(e.target.checked)}
          onBlur={onBlur}
          disabled={disabled}
          aria-invalid={hasError ? 'true' : undefined}
          aria-describedby={[
            hasError ? errorId : null,
            props.helpText ? helpId : null,
          ].filter(Boolean).join(' ') || undefined}
          aria-required={props.required || undefined}
        />
        {props.label}
        {props.required && <span aria-hidden="true"> *</span>}
      </label>
      {props.helpText && (
        <p id={helpId}>{props.helpText}</p>
      )}
      {hasError && (
        <p id={errorId} role="alert">
          {error[0].message}
        </p>
      )}
    </div>
  );
};
```

For checkboxes, the `label` element wraps the input rather than using `htmlFor`. Both approaches are valid, but wrapping provides a larger click target and keeps the label and input tightly associated.

Error Summary Pattern [#error-summary-pattern]

When a form has multiple errors, displaying a summary at the top helps users understand what needs to be fixed. Each error links to the corresponding field, enabling keyboard navigation to the problem.

RilayKit does not provide a built-in error summary component, but you can build one using `useFormStoreApi` to access the form state:

```tsx title="components/error-summary.tsx"
import { useFormStoreApi } from '@rilaykit/forms';
import { useStore } from 'zustand';

function ErrorSummary() {
  const store = useFormStoreApi();
  const errors = useStore(store, (state) => state.errors);

const fieldIds = Object.keys(errors).filter(
    (fieldId) => errors[fieldId].length > 0
  );

if (fieldIds.length === 0) return null;

return (
    <div role="alert" aria-labelledby="error-summary-title">
      <h2 id="error-summary-title">
        There are errors in your form
      </h2>
      <ul>
        {fieldIds.map((fieldId) => (
          <li key={fieldId}>
            <a href={`#${fieldId}`}>
              {errors[fieldId][0].message}
            </a>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

Place this component inside the `<Form>` provider, before the form body:

```tsx
<Form formConfig={formConfig} onSubmit={handleSubmit}>
  <ErrorSummary />
  <FormBody />
  <FormSubmitButton>Submit</FormSubmitButton>
</Form>
```

The `role="alert"` on the container ensures screen readers announce the error summary when it appears. The anchor links (`href="#fieldId"`) move focus to the corresponding field when clicked, since the `id` attribute on each input matches the field's `id` from the form configuration.

Conditional Fields and Live Regions [#conditional-fields-and-live-regions]

RilayKit's condition system can show, hide, enable, or disable fields based on other field values. When a field appears or disappears, sighted users see the change immediately, but screen reader users need to be notified.

Wrap conditional field areas in an ARIA live region:

```tsx
<Form formConfig={formConfig} onSubmit={handleSubmit}>
  <FormField fieldId="accountType" />
  <div aria-live="polite" aria-atomic="false">
    {/* Fields with visibility conditions will appear and
        disappear here. The live region ensures screen readers
        announce the change. */}
    <FormField fieldId="companyName" />
    <FormField fieldId="companySize" />
  </div>
  <FormSubmitButton>Submit</FormSubmitButton>
</Form>
```

Use `aria-live="polite"` so the announcement waits until the screen reader finishes its current output. Use `aria-atomic="false"` so only the changed content is announced, not the entire region.

<Callout>
  Avoid wrapping the entire form in a live region. This causes screen readers to announce every field change, which quickly becomes overwhelming. Only wrap the areas where fields are conditionally shown or hidden.
</Callout>

Workflow Step Navigation [#workflow-step-navigation]

For multi-step workflows, an accessible stepper helps users understand where they are in the process. Use `aria-current="step"` to indicate the active step.

```tsx title="components/workflow-stepper.tsx"
import type { StepConfig } from '@rilaykit/core';

interface WorkflowStepperProps {
  steps: StepConfig[];
  currentStep: number;
}

function WorkflowStepper({ steps, currentStep }: WorkflowStepperProps) {
  return (
    <nav aria-label="Progress">
      <ol role="list">
        {steps.map((step, index) => (
          <li key={step.id}>
            <span
              aria-current={index === currentStep ? 'step' : undefined}
            >
              Step {index + 1}: {step.title}
            </span>
          </li>
        ))}
      </ol>
    </nav>
  );
}
```

The `nav` element with `aria-label="Progress"` identifies this as a navigation landmark. Screen readers will list it alongside other landmarks on the page. The `aria-current="step"` attribute tells assistive technology which step is currently active.

If you allow users to click on completed steps to navigate back, use `button` elements instead of `span` and add `disabled` for steps that are not yet reachable.

Focus Management [#focus-management]

When navigating between workflow steps, focus should move to the first focusable element of the new step. Without this, keyboard users are left at the top of the page or at the navigation button they just clicked, with no clear indication of where the new content starts.

```tsx title="components/step-content.tsx"
import { useEffect, useRef } from 'react';

function StepContent({ children }: { children: React.ReactNode }) {
  const containerRef = useRef<HTMLDivElement>(null);

useEffect(() => {
    const firstInput = containerRef.current?.querySelector(
      'input, select, textarea'
    );
    if (firstInput instanceof HTMLElement) {
      firstInput.focus();
    }
  }, []);

return <div ref={containerRef}>{children}</div>;
}
```

Use this wrapper around each step's content in your workflow:

```tsx
<Workflow workflowConfig={workflowConfig} onComplete={handleComplete}>
  <StepContent>
    <FormBody />
  </StepContent>
</Workflow>
```

<Callout>
  The `useEffect` in this example runs on mount, which means focus moves when the step first renders. If your workflow uses transitions or animations, you may need to delay the focus call until the animation completes. A `requestAnimationFrame` or a timeout matching your animation duration can help.
</Callout>

Checklist [#checklist]

Use this checklist to verify your implementation meets WCAG 2.1 AA requirements:

* Every form field has a visible `<label>` with matching `htmlFor`/`id`
* Error messages use `role="alert"` or `aria-live="assertive"`
* Invalid fields have `aria-invalid="true"`
* Required fields have `aria-required="true"` and a visual indicator
* Help text is linked via `aria-describedby`
* Conditional fields are wrapped in `aria-live="polite"` regions
* Workflow navigation uses `aria-current="step"`
* Focus moves to the first field when changing steps
* All interactive elements are keyboard accessible
* Color is not the only indicator of errors (use icons, text, or borders alongside color)

# Comparison with Other Libraries

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Overview [#overview]

The React ecosystem offers several excellent form libraries, each with its own philosophy and trade-offs. There is no single "best" library -- the right choice depends on your project's complexity, team preferences, and specific requirements.

RilayKit takes a **schema-first, declarative** approach: you describe your entire form as data (fields, validation, conditions, workflows), and RilayKit handles the rest. This is powerful for complex, multi-step workflows and scenarios where form configurations need to be serialized, stored, or generated dynamically. However, it may be more than what you need for a simple contact form or a single login page.

This page provides an honest comparison to help you make an informed decision.

RilayKit vs React Hook Form [#rilaykit-vs-react-hook-form]

[React Hook Form](https://react-hook-form.com/) (RHF) is the most popular React form library, and for good reason. It is lightweight, performant, and has excellent developer experience with minimal re-renders. If you have worked with React forms, you have likely encountered it.

Key Differences [#key-differences]

* **Configuration model**: RHF is imperative -- you register fields directly in JSX using `register()` or `Controller`. RilayKit is declarative -- you define the entire form structure as a configuration object via the fluent builder API.
* **Rendering strategy**: RHF optimizes performance through refs and uncontrolled inputs, minimizing re-renders. RilayKit uses controlled components through a renderer system, giving you full control over how each field type is rendered.
* **Serialization**: RilayKit form configs are plain data that can be serialized with `.toJSON()` and restored with `.fromJSON()`. RHF forms are runtime objects tied to React component trees and cannot be serialized.
* **Multi-step workflows**: RilayKit has a built-in workflow engine with step navigation, conditional steps, persistence, and analytics. RHF requires external solutions or custom code for multi-step flows.
* **Ecosystem**: RHF has a larger ecosystem with official resolvers, DevTools, and extensive community resources. RilayKit is newer but ships more features out of the box.

Code Comparison [#code-comparison]

A simple login form implemented in both libraries:

<Tabs items={['React Hook Form', 'RilayKit']}>
  <Tab value="React Hook Form">
    ```tsx
    import { useForm } from 'react-hook-form';
    import { zodResolver } from '@hookform/resolvers/zod';
    import { z } from 'zod';
    import { form } from '@rilaykit/forms';

const schema = z.object({
      email: z.string().email(),
      password: z.string().min(8),
    });

function LoginForm() {
      const { register, handleSubmit, formState: { errors } } = useForm({
        resolver: zodResolver(schema),
      });

return (
        <form onSubmit={handleSubmit(onSubmit)}>
          <input {...register('email')} />
          {errors.email && <span>{errors.email.message}</span>}
          <input {...register('password')} type="password" />
          {errors.password && <span>{errors.password.message}</span>}
          <button type="submit">Login</button>
        </form>
      );
    }
    ```
  </Tab>

<Tab value="RilayKit">
    ```tsx
    import { required, email, minLength } from '@rilaykit/core';
    import { Form, FormField } from '@rilaykit/forms';

const loginForm = form.create(rilay, 'login')
      .add({
        id: 'email',
        type: 'input',
        props: { label: 'Email' },
        validation: { validate: [required(), email()] },
      })
      .add({
        id: 'password',
        type: 'input',
        props: { label: 'Password', type: 'password' },
        validation: { validate: [required(), minLength(8)] },
      });

function LoginForm() {
      return (
        <Form formConfig={loginForm} onSubmit={handleLogin}>
          <FormField fieldId="email" />
          <FormField fieldId="password" />
          <button type="submit">Login</button>
        </Form>
      );
    }
    ```
  </Tab>
</Tabs>

Both approaches are concise for a simple form. The difference becomes more apparent as complexity grows -- conditional fields, multi-step flows, and dynamic form generation are where RilayKit's declarative model pays off.

When to Choose React Hook Form [#when-to-choose-react-hook-form]

* Simple, standalone forms where maximum performance matters
* You prefer uncontrolled inputs and ref-based rendering
* You need the large RHF ecosystem (DevTools, resolvers, community examples)
* Your forms do not require serialization or dynamic generation
* You want the smallest possible bundle size

When to Choose RilayKit [#when-to-choose-rilaykit]

* Complex multi-step workflows with conditional navigation
* Form configurations that need to be serialized, stored in a database, or generated from an API
* Multi-brand or multi-tenant applications where the same form logic renders differently per design system
* You want a type-safe component registry with declarative conditions
* You need built-in analytics and persistence for long-running workflows

RilayKit vs Formik [#rilaykit-vs-formik]

[Formik](https://formik.org/) was one of the first popular React form libraries and played a pioneering role in shaping how the community thinks about form management. It introduced many patterns that are now standard.

Key Differences [#key-differences-1]

* **Maintenance status**: Formik has seen reduced maintenance activity in recent years. RilayKit is actively developed and maintained.
* **Rendering approach**: Formik uses controlled inputs with `<Field>` and `<ErrorMessage>` components that render HTML directly. RilayKit is fully headless -- it produces no HTML output, delegating all rendering to your component registry.
* **Performance**: Formik has known performance issues with large forms due to its reliance on React context and frequent re-renders. RilayKit's architecture was designed with these lessons in mind.
* **Bundle size**: Formik has a larger bundle footprint. RilayKit's modular architecture lets you import only what you need.
* **Advanced features**: Formik does not provide built-in support for conditional fields, multi-step workflows, serialization, or analytics. These require custom implementation or third-party libraries.

When to Choose Formik [#when-to-choose-formik]

* Legacy projects that already use Formik and where migration cost outweighs the benefits
* Simple forms where Formik's API is already familiar to the team
* Prototyping or quick projects where Formik's `<Field>` components reduce initial setup

When to Choose RilayKit [#when-to-choose-rilaykit-1]

* New projects starting fresh, where you want modern tooling and active maintenance
* Complex forms with conditional logic, validation composition, or cross-field dependencies
* Projects requiring type safety, workflows, serialization, or a headless architecture
* Teams concerned about long-term maintenance and ecosystem health

RilayKit vs TanStack Form [#rilaykit-vs-tanstack-form]

[TanStack Form](https://tanstack.com/form) is the newest major player in the space. It shares many philosophical similarities with RilayKit: TypeScript-first, headless, and focused on type safety. It is the closest competitor in terms of design philosophy.

Key Differences [#key-differences-2]

* **Configuration paradigm**: TanStack Form is field-centric -- you configure and validate each field individually using hooks like `useField`. RilayKit is schema-centric -- you define the entire form as a single configuration object, making it easier to treat forms as data.
* **Serialization**: RilayKit form configs are serializable data structures. TanStack Form configurations include functions and React hooks, which cannot be serialized.
* **Built-in features**: RilayKit ships with a workflow engine, persistence adapter system, analytics callbacks, declarative conditions (`when()`), and a plugin system. TanStack Form focuses on the core form primitives and leaves these concerns to the application.
* **Framework support**: TanStack Form supports React, Vue, Solid, Angular, and Lit through framework adapters. RilayKit is React-only, which allows it to provide deeper React-specific optimizations and patterns.
* **Component registry**: RilayKit's component registry pattern lets you register field types once and reference them by key across all forms. TanStack Form does not have an equivalent built-in concept.

When to Choose TanStack Form [#when-to-choose-tanstack-form]

* Multi-framework projects (Vue, Solid, Angular) where a single form library across frameworks is valuable
* You prefer field-by-field, hook-driven configuration over schema-level declarations
* You are already invested in the TanStack ecosystem (Router, Query, Table) and want consistency
* You want a minimal core and prefer to build higher-level features yourself

When to Choose RilayKit [#when-to-choose-rilaykit-2]

* React-only projects where deep React integration is an advantage
* You need schema-first, serializable form configurations (e.g., form builder tools, CMS-driven forms, stored configs)
* Multi-step workflows with conditional navigation, persistence, and analytics
* You want declarative conditions (`when()`) without writing manual logic
* You value a type-safe component registry pattern for multi-brand or design system projects

Feature Matrix [#feature-matrix]

The following table provides a high-level comparison across key features. Bundle sizes are approximate and may vary depending on tree-shaking and usage.

| Feature                    | RilayKit                    | React Hook Form        | Formik            | TanStack Form              |
| -------------------------- | --------------------------- | ---------------------- | ----------------- | -------------------------- |
| **Type inference**         | Full (schema to props)      | Partial (schema types) | Limited           | Full (field-level)         |
| **Headless**               | Yes                         | No (uses refs)         | No (renders HTML) | Yes                        |
| **Schema validation**      | Standard Schema (native)    | Via resolvers          | Via Yup/Zod       | Built-in + adapters        |
| **Declarative conditions** | Built-in (`when()`)         | Manual                 | Manual            | Manual                     |
| **Multi-step workflows**   | Built-in engine             | External               | External          | External                   |
| **Serialization**          | `.toJSON()` / `.fromJSON()` | No                     | No                | No                         |
| **Component registry**     | Built-in                    | No                     | No                | No                         |
| **Analytics**              | Built-in                    | No                     | No                | No                         |
| **Plugin system**          | Built-in                    | No                     | No                | No                         |
| **Bundle size**            | \~15 KB                     | \~9 KB                 | \~13 KB           | \~10 KB                    |
| **Maintenance**            | Active                      | Active                 | Low activity      | Active                     |
| **Framework support**      | React                       | React                  | React             | React, Vue, Solid, Angular |
| **License**                | MIT                         | MIT                    | Apache 2.0        | MIT                        |

<Callout type="info">
  Bundle sizes are approximate gzipped values and will vary based on what features you import. RilayKit's modular architecture (`@rilaykit/core`, `@rilaykit/forms`, `@rilaykit/workflow`) means you only pay for what you use.
</Callout>

Summary [#summary]

<Callout type="info">
  **Key takeaway**: Every library in this comparison is a solid choice for the right use case. RilayKit shines when you need schema-first forms with multi-step workflows, serializable configurations, declarative conditions, and a type-safe component registry. For simple standalone forms where bundle size and raw performance are the top priorities, lighter libraries like React Hook Form or TanStack Form may be a better fit. Choose the tool that matches your project's actual complexity -- not the one with the longest feature list.
</Callout>

# Debugging

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Debugging dynamic forms and multi-step workflows can be challenging. This guide covers the built-in tools RilayKit provides, reusable debug panel patterns, and solutions to the most common issues.

Development Monitoring [#development-monitoring]

The `DevelopmentAdapter` provides detailed, grouped console output during local development. It logs every monitoring event with structured data, including form events, validation results, workflow transitions, and periodic performance summaries.

```tsx title="lib/monitoring.ts"
import {
  initializeMonitoring,
  getGlobalMonitor,
  DevelopmentAdapter,
} from '@rilaykit/core';

if (process.env.NODE_ENV === 'development') {
  initializeMonitoring({
    enabled: true,
    sampleRate: 1.0,
    flushInterval: 5000,
  }, {
    environment: 'development',
  });

const monitor = getGlobalMonitor();
  monitor?.addAdapter(new DevelopmentAdapter());
}
```

Once initialized, the adapter automatically logs:

* **Form events** -- renders, field changes, validation runs, and submissions.
* **Validation results** -- pass/fail counts, error messages, and durations.
* **Workflow transitions** -- step navigation (forward, backward, skip), step completion, and overall progress.
* **Performance summaries** -- average and max durations grouped by event type, printed at each flush interval.

<Callout type="info">
  Monitoring is entirely opt-in. If you never call `initializeMonitoring`, no events are collected and there is zero runtime overhead. The `DevelopmentAdapter` wraps a `ConsoleAdapter` set to `'debug'` level, so all severity levels are visible.
</Callout>

Form Debug Panel [#form-debug-panel]

A reusable component that displays the current form state directly in the page. Place it inside a `<Form>` component to inspect values, errors, and submit state in real time.

```tsx title="components/form-debug-panel.tsx"
import { useFormValues, useFormSubmitState } from '@rilaykit/forms';
import { useFormStore } from '@rilaykit/forms';
import { useStore } from 'zustand';

function FormDebugPanel() {
  const values = useFormValues();
  const store = useFormStore();
  const errors = useStore(store, (state) => state.errors);
  const submitState = useFormSubmitState();

if (process.env.NODE_ENV === 'production') return null;

return (
    <details open>
      <summary>Form Debug</summary>
      <div style={{ fontFamily: 'monospace', fontSize: 12 }}>
        <h4>Values</h4>
        <pre>{JSON.stringify(values, null, 2)}</pre>
        <h4>Errors</h4>
        <pre>{JSON.stringify(errors, null, 2)}</pre>
        <h4>Submit State</h4>
        <pre>{JSON.stringify(submitState, null, 2)}</pre>
      </div>
    </details>
  );
}
```

Drop it anywhere inside the form tree:

```tsx
<Form formConfig={myForm} onSubmit={handleSubmit}>
  <FormField fieldId="email" />
  <FormField fieldId="password" />
  <FormDebugPanel />
</Form>
```

The panel reads from the Zustand store, so it updates instantly as you type or interact with the form. Because it checks `process.env.NODE_ENV`, it renders nothing in production builds.

Workflow Debug Panel [#workflow-debug-panel]

A similar component for inspecting workflow state. Place it inside a `<WorkflowProvider>` (or `<Workflow>`) to see the current step, visited steps, and navigation state.

```tsx title="components/workflow-debug-panel.tsx"
import {
  useWorkflowContext,
  useCurrentStepIndex,
  useVisitedSteps,
  usePassedSteps,
  useWorkflowNavigationState,
} from '@rilaykit/workflow';

function WorkflowDebugPanel() {
  const workflow = useWorkflowContext();
  const currentStepIndex = useCurrentStepIndex();
  const visitedSteps = useVisitedSteps();
  const passedSteps = usePassedSteps();
  const navigationState = useWorkflowNavigationState();

if (process.env.NODE_ENV === 'production') return null;

return (
    <details open>
      <summary>Workflow Debug</summary>
      <div style={{ fontFamily: 'monospace', fontSize: 12 }}>
        <h4>Current Step</h4>
        <pre>{JSON.stringify({
          index: currentStepIndex,
          step: workflow.currentStep,
        }, null, 2)}</pre>
        <h4>Progress</h4>
        <pre>{JSON.stringify({
          totalSteps: workflow.context.totalSteps,
          visitedSteps: [...visitedSteps],
          passedSteps: [...passedSteps],
        }, null, 2)}</pre>
        <h4>Navigation State</h4>
        <pre>{JSON.stringify(navigationState, null, 2)}</pre>
      </div>
    </details>
  );
}
```

Inspecting Field State [#inspecting-field-state]

For debugging a single field in isolation, `useFieldState` returns the complete state slice for that field -- value, errors, validation state, touched, and dirty flags.

```tsx title="components/field-debug.tsx"
import { useFieldState } from '@rilaykit/forms';

function FieldDebug({ fieldId }: { fieldId: string }) {
  const state = useFieldState(fieldId);

if (process.env.NODE_ENV === 'production') return null;

return (
    <pre style={{ fontSize: 10, opacity: 0.7 }}>
      {JSON.stringify(state, null, 2)}
    </pre>
  );
}
```

Place it next to any `<FormField>` to see exactly what the store holds for that field:

```tsx
<FormField fieldId="email" />
<FieldDebug fieldId="email" />
```

The returned `FieldState` object contains:

```ts
interface FieldState {
  value: unknown;
  errors: ValidationError[];
  validationState: 'idle' | 'validating' | 'valid' | 'invalid';
  touched: boolean;
  dirty: boolean;
}
```

Testing Conditions [#testing-conditions]

Conditions built with `when()` expose an `evaluate()` method, so you can test them outside of React with plain data objects. This is useful for unit tests or quick REPL debugging.

```ts
import { when } from '@rilaykit/core';

// Create a condition
const condition = when('accountType').equals('business');

// Test it with mock data
const result = condition.evaluate({ accountType: 'business' }); // true
const result2 = condition.evaluate({ accountType: 'personal' }); // false
```

Compound conditions work the same way:

```ts
const compound = when('age').greaterThanOrEqual(18)
  .and(when('country').in(['US', 'CA', 'UK']));

compound.evaluate({ age: 21, country: 'US' }); // true
compound.evaluate({ age: 16, country: 'US' }); // false
compound.evaluate({ age: 21, country: 'JP' }); // false
```

<Callout>
  `evaluate()` is synchronous and has no side effects. You can call it as many times as needed in tests without any setup.
</Callout>

Performance Profiling [#performance-profiling]

Every `RilayMonitor` instance includes a `PerformanceProfiler` accessible via `getProfiler()`. Use it to instrument specific code paths with high-resolution timing.

```ts
import { getGlobalMonitor } from '@rilaykit/core';

const monitor = getGlobalMonitor();
const profiler = monitor?.getProfiler();

profiler?.start('form-render');
// ... render form
profiler?.end('form-render');

// Retrieve all collected metrics
console.log(profiler?.getAllMetrics());
```

The profiler also supports marks and measures for more complex timings:

```ts
profiler?.mark('validation-start');
// ... run validation
profiler?.mark('validation-end');
profiler?.measure('full-validation', 'validation-start', 'validation-end');
```

| Method                                | Description                                                               |
| ------------------------------------- | ------------------------------------------------------------------------- |
| `.start(label)`                       | Starts a timer with the given label.                                      |
| `.end(label)`                         | Ends the timer and returns the recorded `PerformanceMetrics`.             |
| `.mark(name)`                         | Places a named timestamp mark via `performance.mark`.                     |
| `.measure(name, startMark, endMark?)` | Measures the duration between two marks.                                  |
| `.getMetrics(label)`                  | Returns the metrics for a specific label.                                 |
| `.getAllMetrics()`                    | Returns all recorded metrics as a `Record<string, PerformanceMetrics>`.   |
| `.clear(label?)`                      | Clears metrics for a specific label, or all metrics if no label is given. |

Common Issues and Solutions [#common-issues-and-solutions]

Field not visible [#field-not-visible]

**Symptoms:** A field defined in the form configuration does not render.

* **Check conditions.** If the field has a `when()` condition on its visibility, verify it references the correct field ID and that the condition evaluates to `true` with the current form data. Use `condition.evaluate(mockData)` to test it in isolation.
* **Verify field IDs match.** The `id` passed to `.add({ id: '...' })` in the form builder must match the `fieldId` prop on `<FormField fieldId="..." />` exactly.
* **Inspect the Form Debug Panel.** Check the current form values to confirm the field that the condition depends on has the expected value.

Validation not running [#validation-not-running]

**Symptoms:** Entering invalid data does not trigger error messages.

* **Check the validation format.** Validation must be specified as `validation: { validate: [...] }`, not `validation: [...]`. The `validate` key is required.
* **Check trigger settings.** By default, validation runs on blur. If you need it on change, set `validateOnChange: true` in the validation config.
* **Verify the field is touched.** Validation on blur only fires once the field has received and lost focus. Use the Field Debug component to check the `touched` state.
* **Check library versions for Standard Schema.** If using Zod, ensure you are on version 3.24 or later, which includes Standard Schema support.

Types not autocompleting [#types-not-autocompleting]

**Symptoms:** TypeScript does not suggest field IDs or types when using the form builder.

* **Pass the correct `rilay` instance to `form.create()`.** The typed `ril` instance is the one returned by `.addComponent()`. Ensure you are passing this instance to `form.create(rilay, ...)`, not a fresh `ril()` call.
* **Reuse a single `rilay` instance.** If the instance is recreated on every call, TypeScript cannot accumulate the registered component types. Export it from a shared module and import it everywhere.
* **Check TypeScript version.** Type-safe chaining requires TypeScript 5.0 or later.

Workflow persistence not working [#workflow-persistence-not-working]

**Symptoms:** Workflow progress is lost on page reload despite persistence being configured.

* **Check the persistence key.** Each workflow must have a unique persistence key. If two workflows share the same key, they will overwrite each other.
* **Verify adapter configuration.** Ensure the adapter is passed to `.configure({ persistence: { ... } })` in the workflow builder.
* **Inspect stored data.** Open the browser DevTools, navigate to the Application tab, and check localStorage for the stored workflow state.

Form submit not firing [#form-submit-not-firing]

**Symptoms:** Clicking the submit button does nothing.

<Tabs items={['Check validation', 'Check button type', 'Check handler']}>
  <Tab value="Check validation">
    Use the Form Debug Panel or `useFormSubmitState()` to check if the form has validation errors. If `isValid` is `false`, submission is blocked.

```tsx
    const { isSubmitting, isValid, isDirty } = useFormSubmitState();
    console.log({ isSubmitting, isValid, isDirty });
    ```
  </Tab>

<Tab value="Check button type">
    Ensure the submit button has `type="submit"` and is placed **inside** the `<Form>` component. A button outside the form tree will not trigger the form's `onSubmit` handler.

```tsx
    <Form formConfig={myForm} onSubmit={handleSubmit}>
      {/* fields */}
      <button type="submit">Submit</button>
    </Form>
    ```
  </Tab>

<Tab value="Check handler">
    Verify that `onSubmit` is passed to the `<Form>` component. Without it, the form has no submission handler to call.

```tsx
    <Form formConfig={myForm} onSubmit={handleSubmit}>
    ```
  </Tab>
</Tabs>

# Internationalization

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="info">
  RilayKit does not include a built-in internationalization system. Because it is headless and schema-first, you can integrate any i18n library (react-intl, next-intl, i18next, etc.) using the patterns described below.
</Callout>

RilayKit's schema-first architecture actually makes internationalization simpler than imperative form libraries. Since field labels, placeholders, validation messages, and step titles are all **data** defined in a configuration object, they can be swapped for their localized equivalents without touching any rendering logic. You describe the form once, and the i18n layer provides the right strings.

This page shows practical integration patterns you can adapt to any i18n library.

Localized Validation Messages [#localized-validation-messages]

All built-in validators accept an optional custom message parameter. Combine this with your i18n library's translation function to produce localized error messages:

```tsx
import { required, email, minLength } from '@rilaykit/core';
import { useTranslation } from 'react-i18next'; // or your i18n library

function useLocalizedForm() {
  const { t } = useTranslation();

return form.create(rilay, 'contact')
    .add({
      id: 'name',
      type: 'input',
      props: { label: t('form.name') },
      validation: { validate: [required(t('validation.required'))] },
    })
    .add({
      id: 'email',
      type: 'input',
      props: { label: t('form.email') },
      validation: { validate: [required(t('validation.required')), email(t('validation.email'))] },
    });
}
```

<Callout type="warn">
  Form configs should be rebuilt when the locale changes, because messages are baked into the configuration at creation time. Use `useMemo` with the current locale as a dependency to avoid unnecessary rebuilds while still reacting to language switches.
</Callout>

```tsx
import { useMemo } from 'react';
import { required } from '@rilaykit/core';
import { Form, FormField } from '@rilaykit/forms';
import { useTranslation } from 'react-i18next';

function LocalizedContactForm() {
  const { t, i18n } = useTranslation();

const form = useMemo(() => form.create(rilay, 'contact')
    .add({
      id: 'name',
      type: 'input',
      props: { label: t('form.name') },
      validation: { validate: [required(t('validation.required'))] },
    }),
    [i18n.language] // Rebuild when locale changes
  );

return (
    <Form formConfig={form} onSubmit={handleSubmit}>
      <FormField fieldId="name" />
    </Form>
  );
}
```

Localized Component Props [#localized-component-props]

Because all component props flow through the schema, localizing labels, placeholders, and option lists is straightforward. Pass translated strings directly into the `props` object:

```tsx
import { form } from '@rilaykit/forms';

const signupForm = form.create(rilay, 'signup')
  .add({
    id: 'country',
    type: 'select',
    props: {
      label: t('form.country'),
      placeholder: t('form.selectCountry'),
      options: [
        { value: 'us', label: t('countries.us') },
        { value: 'fr', label: t('countries.fr') },
        { value: 'de', label: t('countries.de') },
      ],
    },
  });
```

This pattern works with any prop your registered components accept -- option labels, helper text, aria attributes, and more.

Server-Driven Localized Forms [#server-driven-localized-forms]

Because form configs are plain, serializable data, you can generate locale-specific configurations entirely on the server. This is useful for SEO-critical forms, CMS-driven pages, or applications where the form structure itself varies by locale.

<Tabs items={['Server', 'Client']}>
  <Tab value="Server">
    ```tsx
    // server: generate config with the right locale
    const formConfig = generateFormConfig(locale);
    return Response.json(formConfig);
    ```
  </Tab>

<Tab value="Client">
    ```tsx
    import { form } from '@rilaykit/forms';

// client: deserialize and render
    const config = await fetch('/api/form?locale=fr').then(r => r.json());
    const contactForm = form.create(rilay, 'contact').fromJSON(config);
    ```
  </Tab>
</Tabs>

The server can resolve translations, apply locale-specific field ordering, or include region-specific fields before sending the config to the client.

Localized Workflow Steps [#localized-workflow-steps]

The same pattern applies to multi-step workflows. Step titles, descriptions, and all nested field labels can be localized through the translation function:

```tsx
import { useMemo } from 'react';
import { required } from '@rilaykit/core';
import { useTranslation } from 'react-i18next';

function useLocalizedOnboarding() {
  const { t, i18n } = useTranslation();

const workflow = useMemo(() => flow.create(rilay, 'onboarding')
    .step({
      id: 'account',
      title: t('onboarding.steps.account'),
      fields: [
        {
          id: 'email',
          type: 'input',
          props: { label: t('form.email') },
          validation: { validate: [required(t('validation.required'))] },
        },
      ],
    })
    .step({
      id: 'profile',
      title: t('onboarding.steps.profile'),
      fields: [
        {
          id: 'name',
          type: 'input',
          props: { label: t('form.name') },
          validation: { validate: [required(t('validation.required'))] },
        },
      ],
    }),
    [i18n.language]
  );

return workflow;
}
```

The `useMemo` dependency on `i18n.language` ensures the entire workflow config -- including step titles and all nested validation messages -- is rebuilt when the user switches locale.

RTL Support [#rtl-support]

RilayKit does not interfere with text direction. Because it is headless, RTL (right-to-left) support is purely a CSS and HTML concern handled by your renderers. Set the `dir` attribute at the level that makes sense for your application:

```tsx
import type { ComponentRenderProps } from '@rilaykit/core';

interface InputProps {
  label: string;
  placeholder?: string;
}

const Input: React.FC<ComponentRenderProps<InputProps>> = ({ id, value, onChange, props }) => (
  <div dir="auto">
    <label htmlFor={id}>{props.label}</label>
    <input
      id={id}
      value={value || ''}
      onChange={(e) => onChange?.(e.target.value)}
    />
  </div>
);
```

Using `dir="auto"` lets the browser determine the text direction based on content. For full RTL layouts, set `dir="rtl"` on a parent element or the `<html>` tag and let your CSS handle the rest. RilayKit will not conflict with any direction-related styles.

Best Practices [#best-practices]

* **Rebuild configs on locale change.** Use `useMemo` with the locale as a dependency so translated strings stay in sync.
* **Keep validation messages in your i18n files.** Centralizing messages in translation files makes them easier to maintain and review across locales.
* **Use server-driven configs for SEO-critical forms.** Generating fully localized configs on the server avoids layout shifts and ensures search engines see the right content.
* **Test with RTL locales.** If your application supports Arabic, Hebrew, or other RTL languages, verify that your renderers handle `dir="rtl"` correctly.
* **Account for pluralization.** Validation messages like "minimum 1 character" vs "minimum 8 characters" require proper plural rules. Most i18n libraries handle this natively -- use their pluralization features rather than string concatenation.
* **Avoid hardcoding fallback strings.** Let your i18n library handle fallbacks so missing translations are caught during development, not discovered in production.

# Real-World Examples

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Steps, Step } from 'fumadocs-ui/components/steps';

Real-World Examples [#real-world-examples]

These examples demonstrate how RilayKit handles production scenarios end to end. Each one includes the complete configuration -- form and workflow definitions, conditional logic, validation rules, persistence, and analytics -- so you can adapt them directly to your own applications.

***

SaaS Onboarding Flow [#saas-onboarding-flow]

A 4-step onboarding workflow that collects account credentials, company information, team setup, and billing preferences. It uses persistence to save progress across sessions and analytics to track funnel completion.

<Steps>
  <Step>
    Define the forms for each step [#define-the-forms-for-each-step]

Each step has its own form configuration with validation and conditions.

```tsx title="config/onboarding-forms.ts"
    import { ril, required, email, minLength, when } from '@rilaykit/core';
        import { form } from '@rilaykit/forms';

// Assumes components are registered on the ril instance
    const rilay = ril.create()
      .addComponent('input', { renderer: Input })
      .addComponent('select', { renderer: Select })
      .addComponent('textarea', { renderer: Textarea });

// Step 1 - Account Setup
    const accountForm = form.create(rilay, 'onboarding-account')
      .add({
        id: 'name',
        type: 'input',
        props: { label: 'Full Name', placeholder: 'Jane Doe' },
        validation: { validate: [required()] },
      })
      .add({
        id: 'email',
        type: 'input',
        props: { label: 'Email Address', type: 'email', placeholder: 'jane@acme.com' },
        validation: { validate: [required(), email()] },
      })
      .add({
        id: 'password',
        type: 'input',
        props: { label: 'Password', type: 'password' },
        validation: { validate: [required(), minLength(8)] },
      });

// Step 2 - Company Details
    const companyForm = form.create(rilay, 'onboarding-company')
      .add({
        id: 'companyName',
        type: 'input',
        props: { label: 'Company Name', placeholder: 'Acme Inc.' },
        validation: { validate: [required()] },
      })
      .add({
        id: 'companySize',
        type: 'select',
        props: {
          label: 'Company Size',
          options: [
            { value: '1-10', label: '1-10 employees' },
            { value: '11-50', label: '11-50 employees' },
            { value: '51-200', label: '51-200 employees' },
            { value: '200+', label: '200+ employees' },
          ],
        },
        validation: { validate: [required()] },
      })
      .add({
        id: 'industry',
        type: 'select',
        props: {
          label: 'Industry',
          options: [
            { value: 'technology', label: 'Technology' },
            { value: 'finance', label: 'Finance' },
            { value: 'healthcare', label: 'Healthcare' },
            { value: 'other', label: 'Other' },
          ],
        },
        validation: { validate: [required()] },
      });

// Step 3 - Team Configuration
    const teamForm = form.create(rilay, 'onboarding-team')
      .add({
        id: 'teamName',
        type: 'input',
        props: { label: 'Team Name', placeholder: 'Engineering' },
        validation: { validate: [required()] },
      })
      .add({
        id: 'inviteEmails',
        type: 'textarea',
        props: {
          label: 'Invite Team Members',
          placeholder: 'alice@acme.com, bob@acme.com',
        },
      })
      .add({
        id: 'role',
        type: 'select',
        props: {
          label: 'Default Role',
          options: [
            { value: 'admin', label: 'Admin' },
            { value: 'member', label: 'Member' },
            { value: 'viewer', label: 'Viewer' },
          ],
        },
      });

// Step 4 - Billing
    const billingForm = form.create(rilay, 'onboarding-billing')
      .add({
        id: 'plan',
        type: 'select',
        props: {
          label: 'Plan',
          options: [
            { value: 'free', label: 'Free' },
            { value: 'pro', label: 'Pro' },
            { value: 'enterprise', label: 'Enterprise' },
          ],
        },
        validation: { validate: [required()] },
      })
      .add({
        id: 'cardNumber',
        type: 'input',
        props: { label: 'Card Number', placeholder: '4242 4242 4242 4242' },
        validation: { validate: [required('Card number is required for paid plans')] },
        conditions: {
          visible: when('plan').notEquals('free'),
        },
      });
    ```
  </Step>

<Step>
    Build the workflow with persistence and analytics [#build-the-workflow-with-persistence-and-analytics]

Chain the steps together and configure persistence to save progress in localStorage. Analytics callbacks track each step of the funnel.

```tsx title="config/onboarding-workflow.ts"
    import { LocalStorageAdapter } from '@rilaykit/workflow';

<Step>
    Render the onboarding page [#render-the-onboarding-page]

Use the composable workflow components to build the UI. The `<Workflow>` component accepts the builder instance directly -- no need to call `.build()`.

```tsx title="pages/OnboardingPage.tsx"
    import {
      Workflow,
      WorkflowBody,
      WorkflowStepper,
      WorkflowNextButton,
      WorkflowPreviousButton,
      WorkflowSkipButton,
    } from '@rilaykit/workflow';

function OnboardingPage() {
      async function handleComplete(data: Record<string, unknown>) {
        await fetch('/api/onboarding', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(data),
        });
      }

return (
        <Workflow
          workflowConfig={onboarding}
          onWorkflowComplete={handleComplete}
          className="max-w-2xl mx-auto py-12"
        >
          <WorkflowStepper className="mb-8" />

<Callout type="info">
  The `cardNumber` field is only visible (and only validated) when the selected plan is not `free`. When a field is hidden by a visibility condition, RilayKit automatically skips its validation on submit.
</Callout>

***

KYC Identity Verification [#kyc-identity-verification]

A 3-step verification workflow: personal details, document upload, and a final review with legal acknowledgment. This example demonstrates conditional fields based on nationality, a custom async validator for document verification, and persistence to let users resume later.

<Tabs items={['Forms', 'Async Validator', 'Workflow', 'Component']}>
  <Tab value="Forms">
    ```tsx title="config/kyc-forms.ts"
    import { ril, required, when, custom } from '@rilaykit/core';

const rilay = ril.create()
      .addComponent('input', { renderer: Input })
      .addComponent('select', { renderer: Select })
      .addComponent('checkbox', { renderer: Checkbox });

// Step 1 - Personal Information
    const personalInfoForm = form.create(rilay, 'kyc-personal')
      .add({
        id: 'firstName',
        type: 'input',
        props: { label: 'First Name' },
        validation: { validate: [required()] },
      })
      .add({
        id: 'lastName',
        type: 'input',
        props: { label: 'Last Name' },
        validation: { validate: [required()] },
      })
      .add({
        id: 'dateOfBirth',
        type: 'input',
        props: { label: 'Date of Birth', type: 'date' },
        validation: { validate: [required()] },
      })
      .add({
        id: 'nationality',
        type: 'select',
        props: {
          label: 'Nationality',
          options: [
            { value: 'US', label: 'United States' },
            { value: 'GB', label: 'United Kingdom' },
            { value: 'CA', label: 'Canada' },
            { value: 'DE', label: 'Germany' },
            { value: 'FR', label: 'France' },
            { value: 'JP', label: 'Japan' },
            { value: 'AU', label: 'Australia' },
          ],
        },
        validation: { validate: [required()] },
      })
      .add({
        id: 'ssn',
        type: 'input',
        props: { label: 'Social Security Number', placeholder: 'XXX-XX-XXXX' },
        validation: { validate: [required('SSN is required for US nationals')] },
        conditions: {
          visible: when('nationality').equals('US'),
        },
      });

// Step 2 - Document Upload
    const documentForm = form.create(rilay, 'kyc-document')
      .add({
        id: 'documentType',
        type: 'select',
        props: {
          label: 'Document Type',
          options: [
            { value: 'passport', label: 'Passport' },
            { value: 'drivers-license', label: "Driver's License" },
            { value: 'national-id', label: 'National ID' },
          ],
        },
        validation: { validate: [required()] },
      })
      .add({
        id: 'documentNumber',
        type: 'input',
        props: { label: 'Document Number' },
        validation: {
          validate: [required(), validateDocument],
          validateOnBlur: true,
          debounceMs: 500,
        },
      })
      .add({
        id: 'expirationDate',
        type: 'input',
        props: { label: 'Expiration Date', type: 'date' },
        validation: { validate: [required()] },
      });

// Step 3 - Review
    const reviewForm = form.create(rilay, 'kyc-review')
      .add({
        id: 'termsAccepted',
        type: 'checkbox',
        props: { label: 'I accept the terms and conditions' },
        validation: {
          validate: [custom((value) => value === true, 'You must accept the terms')],
        },
      })
      .add({
        id: 'certifyAccurate',
        type: 'checkbox',
        props: { label: 'I certify that all information provided is accurate' },
        validation: {
          validate: [custom((value) => value === true, 'You must certify accuracy')],
        },
      });
    ```
  </Tab>

<Tab value="Async Validator">
    ```tsx title="config/kyc-validators.ts"
    import { custom } from '@rilaykit/core';

The `custom()` validator receives the current form data through its `context` parameter, allowing cross-field validation. Here, the document type is sent alongside the number so the backend can apply format-specific checks (passport vs. national ID, etc.).
  </Tab>

<Tab value="Workflow">
    ```tsx title="config/kyc-workflow.ts"
    import { LocalStorageAdapter } from '@rilaykit/workflow';

<Tab value="Component">
    ```tsx title="pages/KycPage.tsx"
    import {
      Workflow,
      WorkflowBody,
      WorkflowStepper,
      WorkflowNextButton,
      WorkflowPreviousButton,
    } from '@rilaykit/workflow';

function KycPage() {
      async function handleComplete(data: Record<string, unknown>) {
        await fetch('/api/kyc/submit', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(data),
        });
      }

return (
        <Workflow
          workflowConfig={kycWorkflow}
          onWorkflowComplete={handleComplete}
          className="max-w-xl mx-auto py-12"
        >
          <WorkflowStepper className="mb-8" />

<Callout>
  The `ssn` field is only shown when the user selects `US` as their nationality. Its validation is skipped entirely for non-US nationals, so the form can be submitted without it.
</Callout>

***

Dynamic Pricing Calculator [#dynamic-pricing-calculator]

A single-page form (not a workflow) with multiple conditional fields that adapt based on the selected service type. This pattern is common for quote generators, booking forms, and pricing pages where the visible fields depend on user choices.

<Tabs items={['Form Definition', 'Component']}>
  <Tab value="Form Definition">
    ```tsx title="config/pricing-form.ts"
    import { ril, required, when, custom } from '@rilaykit/core';

const rilay = ril.create()
      .addComponent('input', { renderer: Input })
      .addComponent('select', { renderer: Select })
      .addComponent('checkbox-group', { renderer: CheckboxGroup });

<Tab value="Component">
    ```tsx title="pages/PricingPage.tsx"
    import { Form, FormField } from '@rilaykit/forms';

function PricingPage() {
      function handleSubmit(data: Record<string, unknown>) {
        console.log('Pricing request:', data);
        // Send to backend for quote generation
      }

return (
        <div className="max-w-lg mx-auto py-12">
          <h1 className="text-2xl font-bold mb-6">Get a Quote</h1>

<button
                type="submit"
                className="w-full bg-blue-600 text-white py-2 px-4 rounded hover:bg-blue-700"
              >
                Request Quote
              </button>
            </div>
          </Form>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

The `teamSize` field appears only when the service type is `development`, and `designRevisions` appears only for `design` projects. All other fields remain visible regardless of the selection. Hidden fields are excluded from validation and from the submitted data.

***

<Callout type="info">
  These examples show configuration patterns. Adapt them to your specific business requirements and design system. For more basic examples, see the [Examples](/docs/examples) page.
</Callout>

# Advanced Workflows

import { Callout } from 'fumadocs-ui/components/callout';

This guide covers advanced features of the `flow` builder for building dynamic, data-driven workflows.

Dynamic Step Management [#dynamic-step-management]

You can modify steps after the builder is initialized. All methods are chainable.

```tsx
import { rilay } from '@/lib/rilay';

const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
  .step({ id: 'step-1', title: 'Step 1', formConfig: step1Form });

// Add steps conditionally
if (user.isAdmin) {
  workflow.step({ id: 'admin', title: 'Admin Setup', formConfig: adminForm });
}

// Update a step's configuration
workflow.updateStep('step-1', { title: 'Welcome' });

// Remove a step
workflow.removeStep('admin');
```

Step Management API [#step-management-api]

| Method                         | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `.updateStep(stepId, updates)` | Updates an existing step. Throws if not found. |
| `.removeStep(stepId)`          | Removes a step by ID.                          |
| `.getStep(stepId)`             | Returns the step config or `undefined`.        |
| `.getSteps()`                  | Returns a copy of all step configurations.     |
| `.clearSteps()`                | Removes all steps.                             |

The onAfterValidation Callback [#the-onaftervalidation-callback]

The most powerful feature for cross-step data management. This callback runs **after** a step's form validation passes but **before** navigation to the next step.

```tsx
const workflow = flow.create(rilay, 'business-onboarding', 'Business Onboarding')
  .step({
    id: 'registration',
    title: 'Business Registration',
    formConfig: registrationForm,
    onAfterValidation: async (stepData, helper, context) => {
      // stepData contains the validated form data from this step
      const { country, registrationNumber } = stepData;

// Call an external API
      const businessData = await validateBusiness(registrationNumber, country);

// Pre-fill the next step's fields
      helper.setStepFields('company-details', {
        companyName: businessData.name,
        legalForm: businessData.legalForm,
        address: businessData.address,
      });
    },
  })
  .step({
    id: 'company-details',
    title: 'Company Details',
    formConfig: companyDetailsForm,
  });
```

<Callout type="warn">
  Throwing an error inside `onAfterValidation` prevents navigation to the next step. Use this for server-side validation or API checks that must pass before proceeding.
</Callout>

StepDataHelper [#stepdatahelper]

The `helper` parameter provides methods to manipulate data across steps:

```ts
interface StepDataHelper {
  // Target a specific step
  setStepData(stepId: string, data: Record<string, any>): void;
  setStepFields(stepId: string, fields: Record<string, any>): void; // merges with existing
  getStepData(stepId: string): Record<string, any>;

// Target the next step
  setNextStepField(fieldId: string, value: any): void;
  setNextStepFields(fields: Record<string, any>): void; // merges with existing

// Global access
  getAllData(): Record<string, any>;
  getSteps(): StepConfig[];
}
```

**Key difference**: `setStepData` replaces the entire step's data, while `setStepFields` merges with existing data.

Cloning [#cloning]

Create variations of a workflow with `.clone()`:

```tsx
const baseWorkflow = flow.create(rilay, 'base', 'Base Onboarding')
  .step({ id: 'welcome', title: 'Welcome', formConfig: welcomeForm })
  .step({ id: 'profile', title: 'Profile', formConfig: profileForm });

// Create a variant with an extra step
const enterpriseWorkflow = baseWorkflow
  .clone('enterprise', 'Enterprise Onboarding')
  .step({ id: 'billing', title: 'Billing', formConfig: billingForm });
```

Serialization [#serialization]

Export and import workflow definitions as JSON for storage or visual editors.

```tsx
// Export
const workflow = flow.create(rilay, 'survey', 'Survey')
  .step({ id: 'q1', title: 'Question 1', formConfig: q1Form });

const json = workflow.toJSON();
// Store in database, send to API, etc.

// Import
const restored = flow.create(rilay, 'survey-restored', 'Survey')
  .fromJSON(json);

const config = restored.build();
```

Validation [#validation]

The `.validate()` method checks the builder configuration for common errors before building:

```tsx
const errors = workflow.validate();
// Returns string[] — empty if valid
// Checks: at least 1 step, unique step IDs, plugin dependencies
```

`.build()` calls `.validate()` internally and throws if errors are found.

Introspection [#introspection]

Get a statistical overview of your workflow:

```tsx
const stats = workflow.getStats();
// {
//   totalSteps: 3,
//   totalFields: 12,
//   averageFieldsPerStep: 4,
//   maxFieldsInStep: 6,
//   minFieldsInStep: 2,
//   hasAnalytics: true,
// }
```

Complete Example [#complete-example]

```tsx
import { rilay, required, email, when } from '@rilaykit/core';
import { Workflow, WorkflowBody, WorkflowStepper, WorkflowNextButton, WorkflowPreviousButton } from '@rilaykit/workflow';

// Build forms
const personalForm = form.create(rilay, 'personal')
  .add(
    { id: 'firstName', type: 'text', props: { label: 'First Name' }, validation: { validate: [required()] } },
    { id: 'lastName', type: 'text', props: { label: 'Last Name' }, validation: { validate: [required()] } }
  )
  .add({ id: 'email', type: 'text', props: { label: 'Email' }, validation: { validate: [required(), email()] } });

const preferencesForm = form.create(rilay, 'preferences')
  .add({ id: 'plan', type: 'select', props: { label: 'Plan', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }] } });

// Build workflow
const onboarding = flow.create(rilay, 'onboarding', 'User Onboarding')
  .step({
    id: 'personal',
    title: 'Personal Info',
    formConfig: personalForm,
    onAfterValidation: async (data, helper) => {
      // Check if email already exists
      const exists = await checkEmailExists(data.email);
      if (exists) throw new Error('Email already registered');
    },
  })
  .step({
    id: 'preferences',
    title: 'Preferences',
    formConfig: preferencesForm,
    allowSkip: true,
  })
  .configure({
    analytics: {
      onWorkflowComplete: (id, totalTime) => {
        trackEvent('onboarding_complete', { duration: totalTime });
      },
    },
  });

// Render
function OnboardingPage() {
  return (
    <Workflow workflowConfig={onboarding} onWorkflowComplete={handleComplete}>
      <WorkflowStepper />
      <WorkflowBody />
      <div className="flex justify-between mt-6">
        <WorkflowPreviousButton />
        <WorkflowNextButton />
      </div>
    </Workflow>
  );
}
```

# Analytics

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Rilaykit workflows expose a callback-based analytics system that fires events at key lifecycle moments: workflow start, step transitions, step skips, errors, and final completion. You can wire these callbacks to any analytics provider -- Segment, Mixpanel, PostHog, or your own backend.

WorkflowAnalytics Interface [#workflowanalytics-interface]

The analytics configuration is an object with optional callbacks for each lifecycle event:

```ts
interface WorkflowAnalytics {
  /** Fires once when the workflow mounts */
  onWorkflowStart?(workflowId: string, context: WorkflowContext): void;

/** Fires when the last step is successfully submitted */
  onWorkflowComplete?(
    workflowId: string,
    totalTime: number,
    allData: Record<string, any>
  ): void;

/** Fires when a user abandons the workflow (e.g., closes the page) */
  onWorkflowAbandon?(
    workflowId: string,
    currentStep: string,
    data: any
  ): void;

/** Fires when a step becomes active */
  onStepStart?(
    stepId: string,
    timestamp: number,
    context: WorkflowContext
  ): void;

/** Fires when the user leaves a step (navigates forward) */
  onStepComplete?(
    stepId: string,
    duration: number,
    stepData: Record<string, any>,
    context: WorkflowContext
  ): void;

/** Fires when a step is skipped */
  onStepSkip?(
    stepId: string,
    reason: string,
    context: WorkflowContext
  ): void;

/** Fires when any error occurs during navigation or submission */
  onError?(error: Error, context: WorkflowContext): void;
}
```

Callback Parameters [#callback-parameters]

| Parameter    | Description                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `workflowId` | The ID string you defined on the `flow` builder.                                                   |
| `context`    | The full `WorkflowContext` at the time of the event (current step, all data, visited steps, etc.). |
| `totalTime`  | Elapsed time in milliseconds from workflow start to completion.                                    |
| `duration`   | Time in milliseconds the user spent on the completed step.                                         |
| `stepData`   | The data collected on the step that just completed.                                                |
| `reason`     | A string indicating why the step was skipped (e.g., `"user_skip"`).                                |

***

Configuration [#configuration]

Pass an analytics object inside `.configure()` on your workflow builder:

```tsx
const workflow = flow.create(rilay, 'onboarding', 'User Onboarding')
  .step({
    id: 'personal-info',
    title: 'Personal Info',
    formConfig: personalInfoForm,
  })
  .step({
    id: 'preferences',
    title: 'Preferences',
    formConfig: preferencesForm,
    allowSkip: true,
  })
  .step({
    id: 'review',
    title: 'Review',
    formConfig: reviewForm,
  })
  .configure({
    analytics: {
      onWorkflowStart: (id, context) => {
        console.log(`Workflow "${id}" started with ${context.totalSteps} steps`);
      },
      onStepStart: (stepId, timestamp) => {
        console.log(`Step "${stepId}" started at ${new Date(timestamp).toISOString()}`);
      },
      onStepComplete: (stepId, duration, stepData) => {
        trackEvent('step_complete', {
          stepId,
          duration,
          fieldsCompleted: Object.keys(stepData).length,
        });
      },
      onStepSkip: (stepId, reason) => {
        trackEvent('step_skipped', { stepId, reason });
      },
      onWorkflowComplete: (id, totalTime, allData) => {
        trackEvent('workflow_complete', {
          workflowId: id,
          totalTimeSeconds: Math.round(totalTime / 1000),
          stepsCompleted: Object.keys(allData).length,
        });
      },
      onError: (error, context) => {
        captureException(error, {
          tags: {
            workflowId: context.workflowId,
            stepIndex: context.currentStepIndex,
          },
        });
      },
    },
  });
```

***

Integration Examples [#integration-examples]

<Tabs items={['Segment', 'PostHog', 'Custom Backend']}>
  <Tab value="Segment">
    ```tsx
    import { analytics } from '@/lib/segment';

.configure({
      analytics: {
        onWorkflowStart: (id) => {
          analytics.track('Workflow Started', { workflowId: id });
        },
        onStepComplete: (stepId, duration) => {
          analytics.track('Workflow Step Completed', {
            stepId,
            durationMs: duration,
          });
        },
        onWorkflowComplete: (id, totalTime) => {
          analytics.track('Workflow Completed', {
            workflowId: id,
            totalTimeMs: totalTime,
          });
        },
        onStepSkip: (stepId, reason) => {
          analytics.track('Workflow Step Skipped', { stepId, reason });
        },
      },
    })
    ```
  </Tab>

<Tab value="PostHog">
    ```tsx
    import posthog from 'posthog-js';

.configure({
      analytics: {
        onWorkflowStart: (id) => {
          posthog.capture('workflow_started', { workflow_id: id });
        },
        onStepComplete: (stepId, duration, stepData) => {
          posthog.capture('workflow_step_completed', {
            step_id: stepId,
            duration_ms: duration,
            fields_count: Object.keys(stepData).length,
          });
        },
        onWorkflowComplete: (id, totalTime) => {
          posthog.capture('workflow_completed', {
            workflow_id: id,
            total_time_ms: totalTime,
          });
        },
        onError: (error) => {
          posthog.capture('workflow_error', {
            error_message: error.message,
          });
        },
      },
    })
    ```
  </Tab>

<Tab value="Custom Backend">
    ```tsx
    async function sendAnalyticsEvent(
      event: string,
      payload: Record<string, any>
    ) {
      await fetch('/api/analytics', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ event, ...payload, timestamp: Date.now() }),
      });
    }

.configure({
      analytics: {
        onWorkflowStart: (id) => {
          sendAnalyticsEvent('workflow.started', { workflowId: id });
        },
        onStepComplete: (stepId, duration, stepData) => {
          sendAnalyticsEvent('workflow.step_completed', {
            stepId,
            duration,
            data: stepData,
          });
        },
        onWorkflowComplete: (id, totalTime, allData) => {
          sendAnalyticsEvent('workflow.completed', {
            workflowId: id,
            totalTime,
            data: allData,
          });
        },
        onError: (error, context) => {
          sendAnalyticsEvent('workflow.error', {
            error: error.message,
            stepIndex: context.currentStepIndex,
          });
        },
      },
    })
    ```
  </Tab>
</Tabs>

***

useWorkflowAnalytics Hook [#useworkflowanalytics-hook]

The analytics system is powered internally by the `useWorkflowAnalytics` hook. It manages start times, step durations, and event dispatch.

Return Values [#return-values]

```ts
interface UseWorkflowAnalyticsReturn {
  /** Ref holding the workflow start timestamp (used to compute totalTime) */
  analyticsStartTime: React.MutableRefObject<number>;

/** Manually fire a step skip event */
  trackStepSkip: (stepId: string, reason: string) => void;

/** Manually fire an error event */
  trackError: (error: Error) => void;

/** Track navigation performance (fires to RilayMonitor only) */
  trackNavigation: (fromStep: number, toStep: number, duration: number) => void;

/** Track condition evaluation performance (fires to RilayMonitor only) */
  trackConditionEvaluation: (duration: number, conditionsCount: number) => void;
}
```

Automatic Behavior [#automatic-behavior]

The hook automatically:

1. **Tracks workflow start** -- fires `onWorkflowStart` once on mount.
2. **Tracks step timing** -- records when each step becomes active and fires `onStepComplete` with the computed duration when the user leaves the step.
3. **Tracks step starts** -- fires `onStepStart` each time the current step changes.

You do not need to call any method manually for these events -- they are handled automatically by the `WorkflowProvider`.

***

Integration with Global Monitoring [#integration-with-global-monitoring]

When the Rilaykit global monitor is initialized (via `@rilaykit/monitoring`), analytics events are **automatically forwarded** to it in addition to your custom callbacks. This gives you centralized performance tracking across all workflows.

The monitor receives structured events with the type `workflow_navigation` and includes performance metrics:

```ts
interface WorkflowPerformanceMetrics {
  timestamp: number;
  duration: number;
  workflowId: string;
  stepCount: number;
  currentStepIndex: number;
  navigationDuration: number;
  conditionEvaluationDuration: number;
}
```

Events sent to the monitor include:

* `workflow_start` -- when the workflow initializes
* `step_start` -- when a new step becomes active
* `step_complete` -- when the user leaves a step (with duration)
* `step_skip` -- when a step is skipped (flagged as medium priority)
* Navigation performance (flagged as medium when > 1 second)
* Condition evaluation performance (flagged as medium when > 100ms)
* Errors (via `monitor.trackError`)

<Callout>
  Monitor integration is opt-in. If you have not initialized the global monitor, analytics callbacks work independently with no overhead.
</Callout>

***

Event Timing [#event-timing]

Understanding when each callback fires helps you build accurate funnels:

| Event                | When it fires                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `onWorkflowStart`    | Once, when the `WorkflowProvider` first mounts.                                                                                            |
| `onStepStart`        | Each time the active step changes (including the first step).                                                                              |
| `onStepComplete`     | When the user navigates away from a step. Duration = time between `onStepStart` and `onStepComplete` for that step.                        |
| `onStepSkip`         | When `skipStep()` is called or a step is skipped due to conditions. The `reason` is `"user_skip"` for manual skips.                        |
| `onWorkflowComplete` | After the last step is submitted and `onWorkflowComplete` (the prop on `<Workflow>`) resolves. `totalTime` = time since `onWorkflowStart`. |
| `onError`            | On any caught error during navigation, validation callbacks, or submission.                                                                |

# Building Workflows

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';

A workflow is a sequence of steps, where each step is usually a Rilaykit form. The workflow builder allows you to chain these steps together and configure the navigation logic between them.

The flow Builder [#the-flow-builder]

The `flow` class provides a static factory method to build multi-step workflows. It follows the same builder pattern as forms, with method chaining and full type safety.

<Steps>
  <Step>
    1. Create your Form Configurations [#1-create-your-form-configurations]

First, you need a `formConfig` for each step of your workflow. You'll create these using the standard form builder.

```tsx
    import { rilay } from '@/lib/rilay';

const personalInfoForm = rilay.form('personal-info').add(...).build();
    const preferencesForm = rilay.form('preferences').add(...).build();
    const reviewForm = rilay.form('review').add(...).build();
    ```

<Callout>
      You can also pass a `form` builder instance directly to a step. It will be built automatically.
    </Callout>
  </Step>

<Step>
    2. Start the Flow Builder [#2-start-the-flow-builder]

Use `.flow()` on your `rilay` instance to begin building your workflow. The workflow ID and name are optional — if not provided, they will be auto-generated.

```tsx
    import { rilay } from '@/lib/rilay';

// With explicit ID and name (recommended for production)
    const workflowBuilder = rilay.flow(
        'user-onboarding',
        'User Onboarding Workflow',
        'A multi-step workflow to onboard new users' // Optional description
      )

// With auto-generated ID and default name (useful for prototyping)
    const quickWorkflow = rilay.flow()
    ```
  </Step>

<Step>
    3. Add Steps [#3-add-steps]

Use `.step()` to add steps to your workflow. You must provide at least a `title` and `formConfig`.

```tsx
    //...
    .step({
      id: 'personal-info',
      title: 'Personal Information',
      description: 'Tell us about yourself',
      formConfig: personalInfoForm,
    })
    .step({
      id: 'preferences',
      title: 'Preferences',
      description: 'Set your preferences',
      formConfig: preferencesForm,
      allowSkip: true, // This step is optional
    })
    .step({
      id: 'review',
      title: 'Review & Feedback',
      description: 'Review your information',
      formConfig: reviewForm,
    })
    // ...
    ```
  </Step>

<Step>
    4. Configure Navigation and Hooks [#4-configure-navigation-and-hooks]

You can configure the overall workflow behavior with the unified `.configure()` method.

```tsx
    // ...
    .configure({
      analytics: {
        onWorkflowStart: (workflowId) => console.log(`Workflow ${workflowId} started.`),
        onStepComplete: (stepId, duration) => console.log(`Step ${stepId} took ${duration}ms.`),
      }
    })
    // ...
    ```
  </Step>

<Step>
    5. Build the Configuration [#5-build-the-configuration]

Finally, call `.build()` to get the final `workflowConfig` object.

```tsx
    const workflowConfig = rilay.flow(...)
      .step(...)
      .step(...)
      .configure(...)
      .build();
    ```

This configuration can now be passed to the `<Workflow>` component, which will build it automatically if you pass the builder instance.
  </Step>
</Steps>

When to use .build() [#when-to-use-build]

Just like with forms, you often don't need to call `.build()` on a workflow builder. The `<Workflow />` component handles it for you.

You should call `.build()` manually when you need the final, serializable `WorkflowConfig` object, for example, to save it as JSON or for debugging.

Step Configuration [#step-configuration]

The object passed to `.step()` has several options:

* `id` (optional): A unique identifier for the step. Auto-generated if not provided.
* `title` (required): A human-readable title for the step, often shown in the stepper.
* `description` (optional): A short description of the step.
* `formConfig` (required): The form configuration or form builder instance for this step.
* `renderer` (optional): A custom renderer for the body of this specific step.
* `allowSkip` (optional, default: `false`): If `true`, users can skip this step via `<WorkflowSkipButton>`.
* `metadata` (optional): Structured metadata object with `icon`, `category`, `tags`, and custom fields.
* `conditions` (optional): Conditional behavior configuration (visibility, skippable state).
* **`after` (recommended)**: Simplified callback with single parameter containing step data and helpers. See [Advanced Workflows](/docs/workflow/advanced-workflows).
* `onAfterValidation` (deprecated): Legacy 3-parameter callback. Use `after` instead for better DX.

***

Complete Example: User Onboarding Workflow [#complete-example-user-onboarding-workflow]

Let's put it all together. Here is a full example of a 3-step user onboarding workflow.

First, we define the forms for each step:

```tsx
// 1. Define the forms for each step
const accountForm = rilay.form('account-form')
  .add(
    { id: 'email', type: 'email', props: { label: 'Email' }, validation: { validate: [required(), email()] } },
    { id: 'password', type: 'password', props: { label: 'Password' }, validation: { validate: [required(), minLength(8)] } }
  );

const profileForm = rilay.form('profile-form')
  .add(
    { id: 'firstName', type: 'text', props: { label: 'First Name' } },
    { id: 'lastName', type: 'text', props: { label: 'Last Name' } }
  );

const confirmationForm = rilay.form('confirmation-form')
  .add({
    id: 'terms',
    type: 'checkbox', // Assumes a 'checkbox' component is registered
    props: {
      label: 'I agree to the terms and conditions',
    },
    validation: {
      validate: [
        custom(value => value === true, 'You must accept the terms')
      ]
    }
  });
```

<Callout title="About Validation">
  This example uses several built-in validators. To learn more about how validation works in Rilay, check out our in-depth [Field and Form Validation](/docs/forms/validation) guide.
</Callout>

Now, we use the `flow` builder to chain them together into a workflow:

```tsx
// 2. Build the workflow
export const onboardingWorkflow = rilay.flow(
    'onboarding',
    'New User Onboarding'
  )
  .step({
    id: 'account-creation',
    title: 'Create Account',
    formConfig: accountForm,
    metadata: { icon: 'user', category: 'account' },
    after: async (step) => {
      // Simplified callback signature
      console.log('Account created:', step.data.email);

// Pre-fill next step with user's email
      step.next.prefill({
        email: step.data.email
      });
    }
  })
  .step({
    id: 'personal-info',
    title: 'Your Profile',
    formConfig: profileForm,
    metadata: { icon: 'profile', category: 'profile' }
  })
  .step({
    id: 'confirmation',
    title: 'Confirmation',
    formConfig: confirmationForm,
    metadata: { icon: 'check', category: 'confirmation' }
  })
  .configure({
    analytics: {
      onWorkflowStart: (id) => console.log(`Started: ${id}`),
      onWorkflowComplete: (id, totalTime) => console.log(`Completed: ${id} in ${totalTime}ms`),
    },
  });
```

<Callout type="info">
  **New in v0.2:** The simplified `after` callback replaces the verbose `onAfterValidation` (still supported but deprecated).
</Callout>

This `onboardingWorkflow` builder instance is ready to be passed to the `<Workflow />` component, providing a complete multi-step form experience out of the box.

# Workflow Hooks

import { Callout } from 'fumadocs-ui/components/callout';

Like forms, RilayKit workflows use Zustand stores under the hood, exposing granular selector hooks so your components only re-render when the specific state slice they depend on changes. Instead of subscribing to the entire workflow state, you pick the minimal data you need.

All hooks documented on this page are imported from `@rilaykit/workflow`.

```tsx
import {
  useWorkflowContext,
  useCurrentStepIndex,
  useWorkflowActions,
  // ...
} from '@rilaykit/workflow';
```

Context Hook [#context-hook]

`useWorkflowContext()` returns the full workflow context object. It is the most convenient hook for top-level orchestration components, but because it subscribes to the entire state, it will re-render on every state change.

```tsx
import { useWorkflowContext } from '@rilaykit/workflow';

function WorkflowOrchestrator() {
  const workflow = useWorkflowContext();

return (
    <div>
      <p>Step {workflow.workflowState.currentStepIndex + 1} of {workflow.context.totalSteps}</p>
      <button onClick={() => workflow.goNext()}>Next</button>
    </div>
  );
}
```

<Callout>
  Prefer the granular hooks described below for leaf components. Reserve `useWorkflowContext()` for top-level layouts that already depend on many state slices.
</Callout>

Return type [#return-type]

The hook returns an object with the following shape:

```ts
interface WorkflowContextValue {
  workflowState: {
    currentStepIndex: number;
    allData: Record<string, unknown>;
    stepData: Record<string, unknown>;
    visitedSteps: Set<string>;
    passedSteps: Set<string>;
    isSubmitting: boolean;
    isTransitioning: boolean;
    isInitializing: boolean;
  };
  workflowConfig: WorkflowConfig;
  currentStep: StepConfig;
  context: WorkflowContext;
  formConfig?: FormConfiguration;
  conditionsHelpers: UseWorkflowConditionsReturn;
  currentStepMetadata?: Record<string, unknown>;

// Navigation
  goToStep(stepIndex: number): Promise<boolean>;
  goNext(): Promise<boolean>;
  goPrevious(): Promise<boolean>;
  skipStep(): Promise<boolean>;
  canGoToStep(stepIndex: number): boolean;
  canGoNext(): boolean;
  canGoPrevious(): boolean;
  canSkipCurrentStep(): boolean;

// Data
  setValue(fieldId: string, value: unknown): void;
  setStepData(data: Record<string, unknown>): void;
  resetWorkflow(): void;

// Submission
  submitWorkflow(): Promise<void>;
  isSubmitting: boolean;
  canSubmit: boolean;

// Persistence
  persistNow?: () => Promise<void>;
  isPersisting?: boolean;
  persistenceError?: Error | null;
}
```

Granular State Hooks [#granular-state-hooks]

These hooks subscribe to a single slice of the workflow store. A component using `useCurrentStepIndex()` will only re-render when the step index changes, not when field data or submission state updates.

| Hook                           | Returns                                               | Re-renders when              |
| ------------------------------ | ----------------------------------------------------- | ---------------------------- |
| `useCurrentStepIndex()`        | `number`                                              | Step changes                 |
| `useWorkflowTransitioning()`   | `boolean`                                             | Transition state changes     |
| `useWorkflowInitializing()`    | `boolean`                                             | Init state changes           |
| `useWorkflowSubmitting()`      | `boolean`                                             | Submit state changes         |
| `useWorkflowAllData()`         | `Record<string, unknown>`                             | Any data changes             |
| `useWorkflowStepData()`        | `Record<string, unknown>`                             | Current step data changes    |
| `useStepDataById(stepId)`      | `Record<string, unknown> \| undefined`                | Specific step data changes   |
| `useVisitedSteps()`            | `Set<string>`                                         | Visited steps change         |
| `usePassedSteps()`             | `Set<string>`                                         | Passed steps change          |
| `useIsStepVisited(stepId)`     | `boolean`                                             | Step visit state changes     |
| `useIsStepPassed(stepId)`      | `boolean`                                             | Step pass state changes      |
| `useWorkflowNavigationState()` | `{ currentStepIndex, isTransitioning, isSubmitting }` | Navigation state changes     |
| `useWorkflowSubmitState()`     | `{ isSubmitting, isTransitioning, isInitializing }`   | Submit-related state changes |

Usage examples [#usage-examples]

```tsx
import {
  useCurrentStepIndex,
  useWorkflowTransitioning,
  useWorkflowSubmitting,
  useIsStepPassed,
} from '@rilaykit/workflow';

function StepIndicator({ stepId, stepIndex }: { stepId: string; stepIndex: number }) {
  const currentIndex = useCurrentStepIndex();
  const isPassed = useIsStepPassed(stepId);

const isCurrent = currentIndex === stepIndex;

return (
    <div className={isCurrent ? 'step-active' : isPassed ? 'step-passed' : 'step-pending'}>
      Step {stepIndex + 1}
    </div>
  );
}

function SubmitButton() {
  const isSubmitting = useWorkflowSubmitting();
  const isTransitioning = useWorkflowTransitioning();

return (
    <button disabled={isSubmitting || isTransitioning}>
      {isSubmitting ? 'Submitting...' : 'Submit'}
    </button>
  );
}
```

Action Hook [#action-hook]

`useWorkflowActions()` returns an object containing all store mutation functions. It does not subscribe to any state, so the component calling it will not re-render when the store changes.

```ts
import { useWorkflowActions } from '@rilaykit/workflow';

const actions = useWorkflowActions();
```

Available actions:

* `actions.setCurrentStep(index)` -- Set the active step by index.
* `actions.setStepData(data, stepId)` -- Replace the data for a given step.
* `actions.setAllData(data)` -- Replace the entire workflow data object.
* `actions.setFieldValue(fieldId, value, stepId)` -- Set a single field value in a specific step.
* `actions.setSubmitting(bool)` -- Toggle the submitting flag.
* `actions.setTransitioning(bool)` -- Toggle the transitioning flag.
* `actions.setInitializing(bool)` -- Toggle the initializing flag.
* `actions.markStepVisited(stepId)` -- Mark a step as visited.
* `actions.markStepPassed(stepId)` -- Mark a step as passed.
* `actions.reset()` -- Reset the entire workflow store to its initial state.
* `actions.loadPersistedState(state)` -- Hydrate the store from a previously persisted state.

```tsx
import { useWorkflowActions } from '@rilaykit/workflow';

function AdminResetButton() {
  const { reset } = useWorkflowActions();

return <button onClick={reset}>Reset Workflow</button>;
}
```

<Callout title="Low-level API">
  `useWorkflowActions()` exposes the raw Zustand store mutations. For most navigation and data operations, prefer the higher-level methods from `useWorkflowContext()` (such as `goNext()` or `setValue()`), which handle validation, transitions, and side effects automatically.
</Callout>

Step Metadata Hook [#step-metadata-hook]

`useStepMetadata()` provides convenient accessors for step-level metadata defined in your workflow configuration. This is useful for conditional rendering based on arbitrary metadata you attach to steps.

```ts
import { useStepMetadata } from '@rilaykit/workflow';

const metadata = useStepMetadata();
```

Available properties and methods:

* `metadata.current` -- The metadata object for the current step.
* `metadata.getByStepId(stepId)` -- Get metadata for a step by its ID.
* `metadata.getByStepIndex(index)` -- Get metadata for a step by its index.
* `metadata.hasCurrentKey(key)` -- Check if the current step's metadata contains a key.
* `metadata.getCurrentValue<T>(key, defaultValue?)` -- Get a typed value from the current step's metadata, with an optional default.
* `metadata.getAllStepsMetadata()` -- Get metadata for all steps.
* `metadata.findStepsByMetadata(predicate)` -- Find steps whose metadata matches a predicate function.

```tsx
import { useStepMetadata } from '@rilaykit/workflow';

function StepLayout({ children }: { children: React.ReactNode }) {
  const metadata = useStepMetadata();

const showSidebar = metadata.getCurrentValue<boolean>('showSidebar', false);
  const helpText = metadata.getCurrentValue<string>('helpText');

return (
    <div className="step-layout">
      <main>{children}</main>
      {showSidebar && (
        <aside>
          {helpText && <p>{helpText}</p>}
        </aside>
      )}
    </div>
  );
}
```

Condition Hooks [#condition-hooks]

`useWorkflowConditions()` evaluates step and field conditions defined in your workflow configuration. It returns visibility, skip, and field-level condition results for the entire workflow.

```ts
import { useWorkflowConditions } from '@rilaykit/workflow';

const conditions = useWorkflowConditions({
  workflowConfig,
  workflowState,
  currentStep,
});
```

Return value [#return-value]

* `stepConditions` -- `{ visible: boolean; skippable: boolean }` for the current step.
* `fieldConditions` -- `Record<string, ConditionEvaluationResult>` with condition results for each field.
* `allStepConditions` -- `Record<number, StepConditionResult>` with condition results keyed by step index.

Helper methods [#helper-methods]

* `isStepVisible(index)` -- Whether a step should be rendered.
* `isStepSkippable(index)` -- Whether a step can be skipped.
* `isFieldVisible(fieldId)` -- Whether a field should be rendered.
* `isFieldDisabled(fieldId)` -- Whether a field should be disabled.
* `isFieldRequired(fieldId)` -- Whether a field is required.
* `isFieldReadonly(fieldId)` -- Whether a field is read-only.

```tsx
import { useWorkflowContext } from '@rilaykit/workflow';

function ConditionalField({ fieldId, children }: { fieldId: string; children: React.ReactNode }) {
  const { conditionsHelpers } = useWorkflowContext();

if (!conditionsHelpers.isFieldVisible(fieldId)) {
    return null;
  }

return <div data-readonly={conditionsHelpers.isFieldReadonly(fieldId)}>{children}</div>;
}
```

<Callout>
  When using `useWorkflowContext()`, the condition helpers are already available via `conditionsHelpers`. You only need to call `useWorkflowConditions()` directly when building components outside of the standard workflow provider tree.
</Callout>

Best Practices [#best-practices]

* **Use granular hooks for leaf components.** A step indicator only needs `useCurrentStepIndex()` and `useIsStepPassed()`. Subscribing to the full context would cause unnecessary re-renders every time any data changes.
* **Use `useWorkflowContext()` for top-level orchestration.** If a component already depends on navigation, data, and submission state, there is no benefit in splitting across multiple granular hooks.
* **Use `useWorkflowActions()` for programmatic state changes.** Since it does not subscribe to state, components that only dispatch actions (like a reset button) will never re-render due to store changes.
* **Use `useStepMetadata()` for conditional rendering.** Attaching metadata to steps (e.g., `showSidebar`, `requiresAuth`) and reading it through this hook keeps your rendering logic declarative and decoupled from step indices.

# Navigation

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Workflow navigation in Rilaykit is fully managed through the `useWorkflowContext` hook. It handles forward/backward movement, step skipping, validation gating, conditional visibility, and cross-step data manipulation.

Navigation Methods [#navigation-methods]

All navigation methods are available from `useWorkflowContext()`. They return a `Promise<boolean>` indicating whether the navigation succeeded.

```tsx
import { useWorkflowContext } from '@rilaykit/workflow';

function MyNavigation() {
  const { goNext, goPrevious, goToStep, skipStep } = useWorkflowContext();

return (
    <div className="flex gap-2">
      <button onClick={() => goPrevious()}>Back</button>
      <button onClick={() => skipStep()}>Skip</button>
      <button onClick={() => goNext()}>Next</button>
      <button onClick={() => goToStep(0)}>Go to first step</button>
    </div>
  );
}
```

Method Reference [#method-reference]

| Method            | Signature                                 | Description                                                                                                                                                       |
| ----------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `goNext()`        | `() => Promise<boolean>`                  | Validates the current step, runs `onAfterValidation` if defined, marks the step as passed, then advances to the next **visible** step.                            |
| `goPrevious()`    | `() => Promise<boolean>`                  | Navigates to the previous **visible** step. Does not trigger validation.                                                                                          |
| `goToStep(index)` | `(stepIndex: number) => Promise<boolean>` | Jumps to a specific step by its **original** index (not the visible index). Fails if the step is hidden or out of bounds.                                         |
| `skipStep()`      | `() => Promise<boolean>`                  | Skips the current step without validation. Only works if `allowSkip: true` or the step's `skippable` condition evaluates to `true`. Fires `onStepSkip` analytics. |

<Callout>
  `goNext()` is the only navigation method that triggers form validation and `onAfterValidation`. All other methods move directly without validating.
</Callout>

***

Navigation Guards [#navigation-guards]

Guards let you check whether a navigation action is possible before attempting it. Use them to conditionally render or disable buttons.

```tsx
const {
  canGoNext,
  canGoPrevious,
  canGoToStep,
  canSkipCurrentStep,
} = useWorkflowContext();
```

| Guard                  | Signature                        | Returns `true` when                                                                 |
| ---------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
| `canGoNext()`          | `() => boolean`                  | There is a visible step after the current one.                                      |
| `canGoPrevious()`      | `() => boolean`                  | There is a visible step before the current one.                                     |
| `canGoToStep(index)`   | `(stepIndex: number) => boolean` | The target step is within bounds and currently visible.                             |
| `canSkipCurrentStep()` | `() => boolean`                  | The step has `allowSkip: true` **and** the skippable condition evaluates to `true`. |

```tsx
function NavigationButtons() {
  const { goNext, goPrevious, canGoNext, canGoPrevious } = useWorkflowContext();

return (
    <div className="flex justify-between">
      <button
        onClick={() => goPrevious()}
        disabled={!canGoPrevious()}
      >
        Previous
      </button>
      <button
        onClick={() => goNext()}
        disabled={!canGoNext()}
      >
        Next
      </button>
    </div>
  );
}
```

***

Automatic Step Skipping [#automatic-step-skipping]

Invisible steps are **automatically skipped** during navigation. When you call `goNext()` and the next step in sequence is hidden by a condition, the workflow finds the next visible step and jumps to it. The same applies for `goPrevious()`.

```
Steps:  [1: visible] [2: hidden] [3: hidden] [4: visible]

goNext() from step 1  -->  lands on step 4
goPrevious() from step 4  -->  lands on step 1
```

If the current step becomes invisible (e.g., a condition changes while viewing it), the workflow automatically relocates to the nearest visible step -- first looking forward, then backward.

***

Step Conditions [#step-conditions]

Step conditions control **visibility** and **skippability** dynamically based on workflow data. They use the `when()` condition builder from `@rilaykit/core`.

StepConditionalBehavior [#stepconditionalbehavior]

```ts
interface StepConditionalBehavior {
  visible?: ConditionConfig;   // When false, the step is hidden and skipped
  skippable?: ConditionConfig; // When true, the step can be skipped
}
```

Defining Conditions [#defining-conditions]

Use the `when()` builder to create conditions based on data from any step in the workflow.

<Tabs items={['Inline on addStep', 'With addStepConditions']}>
  <Tab value="Inline on addStep">
    ```tsx
    import { when } from '@rilaykit/core';

const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
      .step({
        id: 'personal-info',
        title: 'Personal Info',
        formConfig: personalInfoForm,
      })
      .step({
        id: 'company-info',
        title: 'Company Info',
        formConfig: companyInfoForm,
        conditions: {
          // Only show this step when accountType is "business"
          visible: when('accountType').equals('business').build(),
        },
      })
      .step({
        id: 'preferences',
        title: 'Preferences',
        formConfig: preferencesForm,
        allowSkip: true,
        conditions: {
          // Dynamically make skippable when user has existing preferences
          skippable: when('hasExistingPreferences').equals(true).build(),
        },
      });
    ```
  </Tab>

<Tab value="With addStepConditions">
    ```tsx
    const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
      .step({
        id: 'company-info',
        title: 'Company Info',
        formConfig: companyInfoForm,
      })
      .stepConditions('company-info', {
        visible: when('accountType').equals('business').build(),
      });
    ```
  </Tab>
</Tabs>

<Callout>
  Conditions evaluate against a **flattened** view of all workflow data across all steps. Field values from step `personal-info` are available by their field ID when evaluating conditions on step `company-info`.
</Callout>

How Conditions Affect Navigation [#how-conditions-affect-navigation]

* **`visible: false`** -- The step is excluded from the step list, the stepper, and all navigation. `goNext()` and `goPrevious()` skip over it automatically.
* **`skippable: true`** -- Combined with `allowSkip: true`, the step can be skipped via `skipStep()` or the `<WorkflowSkipButton>`.

***

The onAfterValidation Callback [#the-onaftervalidation-callback]

The `onAfterValidation` callback is a powerful hook that runs **after** a step's form passes validation but **before** the navigation to the next step occurs. It is the right place for:

* API calls triggered by the validated data
* Pre-filling subsequent steps with fetched data
* Custom validation that depends on external services

```tsx
.step({
  id: 'registration',
  title: 'Business Registration',
  formConfig: registrationForm,
  onAfterValidation: async (stepData, helper, context) => {
    // Call an API with the validated data
    const companyInfo = await fetchCompanyBySiren(stepData.siren);

// Pre-fill the next step
    helper.setNextStepFields({
      companyName: companyInfo.name,
      address: companyInfo.address,
    });

// Or target a specific step by ID
    helper.setStepFields('company-details', {
      legalForm: companyInfo.legalForm,
    });
  },
})
```

<Callout type="warn">
  If `onAfterValidation` throws an error, navigation is **cancelled** and the user stays on the current step. Use this to block progression when an API call fails.
</Callout>

Signature [#signature]

```ts
onAfterValidation?: (
  stepData: Record<string, any>,
  helper: StepDataHelper,
  context: WorkflowContext
) => void | Promise<void>;
```

***

StepDataHelper [#stepdatahelper]

The `StepDataHelper` interface provides clean methods to read and modify data across steps from within `onAfterValidation`.

```ts
interface StepDataHelper {
  /** Replace all data for a specific step */
  setStepData(stepId: string, data: Record<string, any>): void;

/** Merge specific fields into a step's existing data */
  setStepFields(stepId: string, fields: Record<string, any>): void;

/** Read the current data for a step */
  getStepData(stepId: string): Record<string, any>;

/** Set a single field value on the next step */
  setNextStepField(fieldId: string, value: any): void;

/** Merge multiple field values into the next step's data */
  setNextStepFields(fields: Record<string, any>): void;

/** Get all data across all steps */
  getAllData(): Record<string, any>;

/** Get the full list of step configurations */
  getSteps(): StepConfig[];
}
```

Usage Patterns [#usage-patterns]

<Tabs items={['Pre-fill next step', 'Target a specific step', 'Read cross-step data']}>
  <Tab value="Pre-fill next step">
    ```tsx
    onAfterValidation: async (stepData, helper) => {
      const result = await lookupCompany(stepData.registrationNumber);

helper.setNextStepFields({
        companyName: result.name,
        address: result.address,
        industry: result.sector,
      });
    }
    ```
  </Tab>

<Tab value="Target a specific step">
    ```tsx
    onAfterValidation: async (stepData, helper) => {
      const result = await lookupCompany(stepData.registrationNumber);

// Pre-fill step 3, even though we are on step 1
      helper.setStepFields('review', {
        summary: `${result.name} - ${result.address}`,
      });
    }
    ```
  </Tab>

<Tab value="Read cross-step data">
    ```tsx
    onAfterValidation: async (stepData, helper, context) => {
      const personalInfo = helper.getStepData('personal-info');
      const allData = helper.getAllData();

// Use data from a previous step to enrich the current call
      await enrichProfile({
        email: personalInfo.email,
        preferences: stepData,
      });
    }
    ```
  </Tab>
</Tabs>

***

Navigation Flow Summary [#navigation-flow-summary]

Here is the complete flow when the user clicks "Next":

<Steps>
  <Step>
    Form validation [#form-validation]

The current step's form is validated using its field validators. If validation fails, errors are shown and navigation is blocked.
  </Step>

<Step>
    onAfterValidation [#onaftervalidation]

If the step defines `onAfterValidation`, it is called with the validated data and the `StepDataHelper`. If it throws, navigation is cancelled.
  </Step>

<Step>
    Step marked as passed [#step-marked-as-passed]

The current step ID is added to the `passedSteps` set, indicating it has been successfully validated.
  </Step>

<Step>
    Find next visible step [#find-next-visible-step]

The workflow scans forward from the current index and finds the next step whose `visible` condition evaluates to `true` (or has no condition). Hidden steps are skipped.
  </Step>

<Step>
    Transition [#transition]

The `onStepChange` callback fires, the current step index updates, and the new step is marked as visited.
  </Step>
</Steps>

# Persistence

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Multi-step workflows can take time to complete. Users may close their browser, lose connectivity, or simply want to finish later. Rilaykit's persistence system saves workflow progress automatically and restores it when the user returns.

How It Works [#how-it-works]

<Steps>
  <Step>
    Configure an adapter [#configure-an-adapter]

Choose a storage backend -- `LocalStorageAdapter` for browser storage, or implement your own adapter for server-side persistence.
  </Step>

<Step>
    Attach to the workflow [#attach-to-the-workflow]

Pass the adapter and options via the `.configure()` method on the `flow` builder.
  </Step>

<Step>
    Automatic save/restore [#automatic-saverestore]

The `WorkflowProvider` detects the persistence configuration, loads any saved state on mount, and auto-saves on every meaningful state change (debounced).
  </Step>
</Steps>

***

LocalStorageAdapter [#localstorageadapter]

The built-in adapter that persists workflow data to the browser's `localStorage`. It is SSR-safe -- all operations silently no-op when `window` is not available.

```tsx
import { LocalStorageAdapter } from '@rilaykit/workflow';

const adapter = new LocalStorageAdapter({
  keyPrefix: 'rilay_workflow_',  // default
  compress: false,               // default, uses btoa/atob when true
  maxAge: undefined,             // milliseconds before data expires
});
```

Constructor Options [#constructor-options]

| Option      | Type                  | Default             | Description                                                                             |
| ----------- | --------------------- | ------------------- | --------------------------------------------------------------------------------------- |
| `keyPrefix` | `string`              | `'rilay_workflow_'` | Prefix added to all localStorage keys for namespace isolation.                          |
| `compress`  | `boolean`             | `false`             | When `true`, data is base64-encoded before storage. Useful for large workflows.         |
| `maxAge`    | `number \| undefined` | `undefined`         | Time-to-live in milliseconds. Expired data is removed on next `load` or `exists` check. |

Methods [#methods]

| Method     | Signature                                                     | Description                                                                                  |
| ---------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `save`     | `(key: string, data: PersistedWorkflowData) => Promise<void>` | Saves workflow data. Handles quota exceeded errors by clearing expired entries and retrying. |
| `load`     | `(key: string) => Promise<PersistedWorkflowData \| null>`     | Loads saved data. Returns `null` if not found or expired.                                    |
| `remove`   | `(key: string) => Promise<void>`                              | Deletes saved data for the given key.                                                        |
| `exists`   | `(key: string) => Promise<boolean>`                           | Checks if non-expired data exists for the key.                                               |
| `listKeys` | `() => Promise<string[]>`                                     | Lists all valid (non-expired) workflow keys.                                                 |
| `clear`    | `() => Promise<void>`                                         | Removes all workflow data matching the key prefix.                                           |

<Callout>
  When `compress` is `true`, the adapter encodes the JSON payload with `btoa()` before writing to localStorage and decodes with `atob()` on read. This is a simple encoding, not a compression algorithm -- consider a library like LZ-String for production use with very large datasets.
</Callout>

***

Configuration via Flow Builder [#configuration-via-flow-builder]

Enable persistence by passing a `persistence` object inside `.configure()`:

```tsx
import { LocalStorageAdapter } from '@rilaykit/workflow';

const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
  .step({
    id: 'personal-info',
    title: 'Personal Info',
    formConfig: personalInfoForm,
  })
  .step({
    id: 'preferences',
    title: 'Preferences',
    formConfig: preferencesForm,
  })
  .configure({
    persistence: {
      adapter: new LocalStorageAdapter({
        maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
      }),
      options: {
        autoPersist: true,
        debounceMs: 500,
      },
      userId: currentUser.id, // Isolates storage per user
    },
  });
```

PersistenceOptions [#persistenceoptions]

| Option        | Type                  | Default     | Description                                                           |
| ------------- | --------------------- | ----------- | --------------------------------------------------------------------- |
| `autoPersist` | `boolean`             | `false`     | Automatically save on every meaningful state change.                  |
| `debounceMs`  | `number`              | `500`       | Delay in ms before the auto-save fires after the last change.         |
| `storageKey`  | `string`              | workflow ID | Override the key used for storage.                                    |
| `metadata`    | `Record<string, any>` | `undefined` | Extra metadata saved alongside workflow data (e.g., version, tenant). |

userId [#userid]

When `userId` is provided, it is appended to the storage key so that different users on the same browser get independent persistence.

***

PersistedWorkflowData [#persistedworkflowdata]

The shape of data that gets saved and loaded:

```ts
interface PersistedWorkflowData {
  workflowId: string;
  currentStepIndex: number;
  allData: Record<string, any>;
  stepData: Record<string, any>;
  visitedSteps: string[];
  passedSteps?: string[];
  lastSaved: number;            // Unix timestamp
  metadata?: Record<string, any>;
}
```

This structure contains everything needed to fully restore the workflow: which step the user was on, all the data they entered, which steps they visited, and which steps passed validation.

***

usePersistence Hook [#usepersistence-hook]

The persistence logic is powered by the `usePersistence` hook. It is used internally by `WorkflowProvider`, but you can interact with its return values through `useWorkflowContext()`.

Return Values [#return-values]

```ts
interface UsePersistenceReturn {
  /** Whether a save operation is currently in progress */
  isPersisting: boolean;

/** The last persistence error, if any */
  persistenceError: WorkflowPersistenceError | null;

/** Trigger an immediate save (bypasses debounce) */
  persistNow: () => Promise<void>;

/** Load persisted data from the adapter */
  loadPersistedData: () => Promise<PersistedWorkflowData | null>;

/** Delete all persisted data for this workflow */
  clearPersistedData: () => Promise<void>;

/** Check if persisted data exists */
  hasPersistedData: () => Promise<boolean>;
}
```

Accessing from Components [#accessing-from-components]

The `persistNow`, `isPersisting`, and `persistenceError` values are surfaced through `useWorkflowContext()`:

```tsx
import { useWorkflowContext } from '@rilaykit/workflow';

function PersistenceIndicator() {
  const { isPersisting, persistenceError, persistNow } = useWorkflowContext();

return (
    <div className="flex items-center gap-2 text-sm text-muted-foreground">
      {isPersisting && <span>Saving...</span>}
      {persistenceError && (
        <span className="text-destructive">
          Save failed: {persistenceError.message}
        </span>
      )}
      <button onClick={() => persistNow?.()}>
        Save now
      </button>
    </div>
  );
}
```

***

Auto-Save Behavior [#auto-save-behavior]

When `autoPersist` is `true`, the hook watches for state changes and saves automatically. It applies several safeguards:

1. **Debouncing** -- Saves are debounced by `debounceMs` (default 500ms) to avoid writing on every keystroke.
2. **Significant change detection** -- Only saves when the step index, data, or visited steps have actually changed.
3. **Skips during transitions** -- No save fires while `isTransitioning`, `isSubmitting`, or `isInitializing` is `true`.
4. **Quota exceeded recovery** -- The `LocalStorageAdapter` clears expired entries and retries when `QuotaExceededError` is thrown.

***

Custom Adapter [#custom-adapter]

Implement the `WorkflowPersistenceAdapter` interface to use any storage backend.

```ts
interface WorkflowPersistenceAdapter {
  save(key: string, data: PersistedWorkflowData): Promise<void>;
  load(key: string): Promise<PersistedWorkflowData | null>;
  remove(key: string): Promise<void>;
  exists(key: string): Promise<boolean>;
  listKeys?(): Promise<string[]>;
  clear?(): Promise<void>;
}
```

Example: Supabase Adapter [#example-supabase-adapter]

<Tabs items={['Implementation', 'Usage']}>
  <Tab value="Implementation">
    ```ts
    import type {
      PersistedWorkflowData,
      WorkflowPersistenceAdapter,
    } from '@rilaykit/workflow';
    import { supabase } from '@/lib/supabase';

export class SupabaseAdapter implements WorkflowPersistenceAdapter {
      private table = 'workflow_progress';

async save(key: string, data: PersistedWorkflowData): Promise<void> {
        const { error } = await supabase
          .from(this.table)
          .upsert({
            key,
            data: JSON.stringify(data),
            updated_at: new Date().toISOString(),
          }, { onConflict: 'key' });

if (error) throw new Error(error.message);
      }

async load(key: string): Promise<PersistedWorkflowData | null> {
        const { data, error } = await supabase
          .from(this.table)
          .select('data')
          .eq('key', key)
          .single();

if (error || !data) return null;
        return JSON.parse(data.data);
      }

async remove(key: string): Promise<void> {
        await supabase.from(this.table).delete().eq('key', key);
      }

async exists(key: string): Promise<boolean> {
        const { count } = await supabase
          .from(this.table)
          .select('key', { count: 'exact', head: true })
          .eq('key', key);

return (count ?? 0) > 0;
      }
    }
    ```
  </Tab>

<Tab value="Usage">
    ```tsx
    const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
      .step(...)
      .configure({
        persistence: {
          adapter: new SupabaseAdapter(),
          options: { autoPersist: true, debounceMs: 1000 },
          userId: currentUser.id,
        },
      });
    ```
  </Tab>
</Tabs>

<Callout>
  The `listKeys()` and `clear()` methods are optional. They are useful for admin tooling or cleanup jobs but are not required by the persistence system.
</Callout>

***

Error Handling [#error-handling]

Persistence errors are wrapped in `WorkflowPersistenceError`, which includes a machine-readable `code`:

| Code               | Meaning                                                       |
| ------------------ | ------------------------------------------------------------- |
| `SAVE_FAILED`      | The save operation failed.                                    |
| `LOAD_FAILED`      | The load operation failed.                                    |
| `REMOVE_FAILED`    | The remove operation failed.                                  |
| `LIST_FAILED`      | Listing keys failed.                                          |
| `CLEAR_FAILED`     | Clearing all data failed.                                     |
| `QUOTA_EXCEEDED`   | localStorage is full and cleanup could not free enough space. |
| `OPERATION_FAILED` | Generic fallback code.                                        |

Errors are surfaced through `persistenceError` in the hook and are also logged to the console with the `[WorkflowPersistence]` prefix.

# Plugins

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

The Rilaykit workflow plugin system lets you encapsulate reusable behavior and inject it into any workflow. Plugins receive the `flow` builder instance during installation, giving them full access to add steps, configure analytics, modify existing steps, and more.

WorkflowPlugin Interface [#workflowplugin-interface]

A plugin is a plain object that implements the `WorkflowPlugin` interface:

```ts
interface WorkflowPlugin {
  /** Unique name identifying the plugin */
  name: string;

/** Semantic version (for dependency resolution and debugging) */
  version?: string;

/** Names of plugins that must be installed before this one */
  dependencies?: string[];

/** Called with the flow builder instance when the plugin is installed */
  install(builder: flow): void;
}
```

***

Using Plugins [#using-plugins]

Install a plugin by calling `.use()` on the `flow` builder. Plugins are installed immediately and have access to the builder at the point of installation.

```tsx
import { rilay } from '@/lib/rilay';

const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
  .use(myPlugin)
  .step({
    id: 'personal-info',
    title: 'Personal Info',
    formConfig: personalInfoForm,
  })
  .step({
    id: 'preferences',
    title: 'Preferences',
    formConfig: preferencesForm,
  })
  .build();
```

You can chain multiple `.use()` calls:

```tsx
const workflow = flow.create(rilay, 'checkout', 'Checkout')
  .use(loggingPlugin)
  .use(validationPlugin)
  .use(analyticsPlugin)
  .step(...)
  .build();
```

<Callout>
  Plugins are called in the order they are installed. If plugin B depends on modifications made by plugin A, install A first.
</Callout>

***

Creating a Plugin [#creating-a-plugin]

A plugin's `install` method receives the `flow` builder instance. You can call any builder method inside it: `addStep`, `configure`, `updateStep`, `addStepConditions`, etc.

Example: Logging Plugin [#example-logging-plugin]

This plugin adds an `onAfterValidation` callback to every existing step that logs the step data:

```tsx
import type { WorkflowPlugin } from '@rilaykit/core';

const loggingPlugin: WorkflowPlugin = {
  name: 'step-logger',
  version: '1.0.0',

install(builder) {
    // Get all steps that have been added so far
    const steps = builder.getSteps();

for (const step of steps) {
      const existingCallback = step.onAfterValidation;

builder.updateStep(step.id, {
        onAfterValidation: async (stepData, helper, context) => {
          console.log(`[step-logger] Step "${step.id}" validated:`, stepData);

// Call the original callback if it existed
          if (existingCallback) {
            await existingCallback(stepData, helper, context);
          }
        },
      });
    }
  },
};
```

Usage:

```tsx
const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
  .step({
    id: 'personal-info',
    title: 'Personal Info',
    formConfig: personalInfoForm,
  })
  .step({
    id: 'preferences',
    title: 'Preferences',
    formConfig: preferencesForm,
  })
  .use(loggingPlugin) // Install AFTER adding steps so getSteps() returns them
  .build();
```

<Callout type="warn">
  Since `install` is called immediately, the plugin only sees steps that have been added **before** `.use()` is called. If you need the plugin to affect all steps, install it after all `.step()` calls.
</Callout>

Example: Analytics Integration Plugin [#example-analytics-integration-plugin]

A plugin that adds analytics tracking to the workflow:

```tsx
import type { WorkflowPlugin } from '@rilaykit/core';

function createAnalyticsPlugin(trackFn: (event: string, data: any) => void): WorkflowPlugin {
  return {
    name: 'analytics-tracker',
    version: '1.0.0',

install(builder) {
      builder.configure({
        analytics: {
          onWorkflowStart: (id) => {
            trackFn('workflow_started', { workflowId: id });
          },
          onStepComplete: (stepId, duration, stepData) => {
            trackFn('step_completed', { stepId, duration });
          },
          onWorkflowComplete: (id, totalTime) => {
            trackFn('workflow_completed', {
              workflowId: id,
              totalTimeSeconds: Math.round(totalTime / 1000),
            });
          },
          onError: (error) => {
            trackFn('workflow_error', { message: error.message });
          },
        },
      });
    },
  };
}

// Usage
const workflow = flow.create(rilay, 'checkout', 'Checkout')
  .step(...)
  .use(createAnalyticsPlugin(posthog.capture))
  .build();
```

Example: Conditional Step Plugin [#example-conditional-step-plugin]

A plugin that adds visibility conditions to specific steps:

```tsx
import type { WorkflowPlugin } from '@rilaykit/core';
import { when } from '@rilaykit/core';

const premiumStepsPlugin: WorkflowPlugin = {
  name: 'premium-steps',
  version: '1.0.0',

install(builder) {
    // Make the "advanced-settings" step visible only for premium users
    try {
      builder.stepConditions('advanced-settings', {
        visible: when('userPlan').equals('premium').build(),
      });
    } catch {
      // Step may not exist in all workflows using this plugin
      console.warn('[premium-steps] Step "advanced-settings" not found, skipping.');
    }
  },
};
```

***

Plugin Dependencies [#plugin-dependencies]

The `dependencies` array declares which plugins must be installed before the current one. The builder validates this at installation time and throws if any dependency is missing.

```tsx
const enhancedLoggingPlugin: WorkflowPlugin = {
  name: 'enhanced-logger',
  version: '1.0.0',
  dependencies: ['step-logger'], // Requires the base logging plugin

install(builder) {
    // This plugin extends the base logger with more detail
    const steps = builder.getSteps();

for (const step of steps) {
      const existingCallback = step.onAfterValidation;

builder.updateStep(step.id, {
        onAfterValidation: async (stepData, helper, context) => {
          console.log(`[enhanced-logger] Step "${step.id}" context:`, {
            currentIndex: context.currentStepIndex,
            totalSteps: context.totalSteps,
            visitedSteps: Array.from(context.visitedSteps),
          });

if (existingCallback) {
            await existingCallback(stepData, helper, context);
          }
        },
      });
    }
  },
};
```

Dependency Resolution [#dependency-resolution]

<Steps>
  <Step>
    Install dependencies first [#install-dependencies-first]

Plugins are checked against the list of already-installed plugins. If a dependency is missing, an error is thrown immediately.
  </Step>

<Step>
    Install the dependent plugin [#install-the-dependent-plugin]

Once all dependencies are satisfied, the plugin's `install` method is called.
  </Step>
</Steps>

```tsx
// This works -- step-logger is installed before enhanced-logger
flow.create(rilay, 'test', 'Test')
  .use(loggingPlugin)          // name: 'step-logger'
  .use(enhancedLoggingPlugin)  // depends on 'step-logger'
  .build();

// This throws -- enhanced-logger's dependency is not satisfied
flow.create(rilay, 'test', 'Test')
  .use(enhancedLoggingPlugin)  // Error: Plugin "enhanced-logger" requires missing dependencies: step-logger
  .build();
```

<Callout type="warn">
  The error message includes the names of all missing dependencies so you know exactly what to install first.
</Callout>

***

Removing Plugins [#removing-plugins]

Use `.removePlugin(pluginName)` to remove a plugin from the builder. Note that this only removes the plugin from the internal registry -- any modifications the plugin made during `install` (added steps, configured analytics, etc.) are **not** rolled back.

```tsx
const workflow = flow.create(rilay, 'onboarding', 'Onboarding')
  .use(loggingPlugin)
  .step(...)
  .removePlugin('step-logger')
  .build();
```

This is primarily useful when cloning a workflow and wanting to swap plugins:

```tsx
const baseWorkflow = flow.create(rilay, 'base', 'Base Workflow')
  .use(productionAnalytics)
  .step(...);

const testWorkflow = baseWorkflow
  .clone('test', 'Test Workflow')
  .removePlugin('production-analytics')
  .use(testAnalytics);
```

***

Validation [#validation]

The `.validate()` method on the builder checks plugin dependencies as part of its validation pass. If a plugin lists a dependency that is no longer installed (e.g., after `removePlugin`), validation reports it.

```tsx
const errors = workflow.validate();
// ["Plugin "enhanced-logger" requires missing dependencies: step-logger"]
```

This is also checked automatically when calling `.build()`, which throws if validation fails.

***

Best Practices [#best-practices]

1. **Name plugins clearly** -- Use descriptive names like `analytics-posthog` or `conditional-premium-steps` so dependency errors are easy to understand.

2. **Install after addStep when accessing steps** -- If your plugin calls `getSteps()` or `updateStep()`, install it after all steps have been added.

3. **Preserve existing callbacks** -- When wrapping `onAfterValidation`, always call the original callback to avoid breaking other plugins or user-defined logic.

4. **Handle missing steps gracefully** -- Not every workflow will have the same steps. Use `try/catch` around `updateStep` and `addStepConditions` calls that target specific step IDs.

5. **Use factory functions** -- When plugins need configuration, wrap them in a factory function that returns a `WorkflowPlugin` object. This makes them reusable across workflows with different settings.

# Rendering Workflows

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Rilaykit provides a set of composable React components that you assemble together to render your workflow UI. Each component handles a specific concern -- body content, navigation, progress -- and delegates its visual rendering to the renderers you registered on your `ril` instance.

Component Overview [#component-overview]

| Component                  | Purpose                                                                |
| -------------------------- | ---------------------------------------------------------------------- |
| `<Workflow>`               | Root wrapper. Resolves config and provides context.                    |
| `<WorkflowBody>`           | Renders the current step's form (or custom renderer).                  |
| `<WorkflowStepper>`        | Progress indicator across visible steps.                               |
| `<WorkflowNextButton>`     | Validates the current step and advances (or submits on the last step). |
| `<WorkflowPreviousButton>` | Navigates back to the previous visible step.                           |
| `<WorkflowSkipButton>`     | Skips the current step when allowed.                                   |
| `<WorkflowProvider>`       | Internal context provider (used by `<Workflow>` under the hood).       |

***

Workflow [#workflow]

The root component that wraps your entire workflow UI. It accepts either a built `WorkflowConfig` object or a `flow` builder instance -- if you pass a builder, it calls `.build()` automatically.

```tsx
import { Workflow } from '@rilaykit/workflow';
```

Props [#props]

| Prop                 | Type                                                           | Required | Description                                                 |
| -------------------- | -------------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| `workflowConfig`     | `WorkflowConfig \| flow`                                       | Yes      | The workflow configuration or builder instance.             |
| `children`           | `React.ReactNode`                                              | Yes      | The layout components to render inside the workflow.        |
| `defaultValues`      | `Record<string, unknown>`                                      | No       | Initial data to pre-populate across steps.                  |
| `defaultStep`        | `string`                                                       | No       | Step ID to start on instead of the first step.              |
| `onStepChange`       | `(from: number, to: number, context: WorkflowContext) => void` | No       | Callback fired on every step transition.                    |
| `onWorkflowComplete` | `(data: Record<string, unknown>) => void \| Promise<void>`     | No       | Callback fired when the last step is submitted.             |
| `className`          | `string`                                                       | No       | CSS class applied to the underlying `FormProvider` wrapper. |

```tsx
<Workflow
  workflowConfig={onboardingFlow}
  defaultValues={{ email: user.email }}
  defaultStep="preferences"
  onStepChange={(from, to) => console.log(`Step ${from} -> ${to}`)}
  onWorkflowComplete={async (data) => {
    await saveOnboarding(data);
    router.push('/dashboard');
  }}
>
  {/* Layout goes here */}
</Workflow>
```

<Callout>
  When you pass a `flow` builder instance, the component memoizes the `.build()` call so it only runs once. You do not need to call `.build()` yourself.
</Callout>

***

WorkflowBody [#workflowbody]

Renders the main content for the current step. If the step defines a custom `renderer`, that renderer is used. Otherwise it falls back to `<FormBody />` from `@rilaykit/forms`, or renders `children` as a fallback.

```tsx
import { WorkflowBody } from '@rilaykit/workflow';
```

Props [#props-1]

| Prop       | Type              | Required | Description                                                                  |
| ---------- | ----------------- | -------- | ---------------------------------------------------------------------------- |
| `stepId`   | `string`          | No       | Only render when the current step matches this ID. Returns `null` otherwise. |
| `children` | `React.ReactNode` | No       | Fallback content rendered when no custom `renderer` is defined on the step.  |

Rendering Priority [#rendering-priority]

1. If the step has no `formConfig`, nothing is rendered.
2. If the step has a custom `renderer`, it is called with the full `StepConfig`.
3. Otherwise, `children` is rendered (or `<FormBody />` when no children are provided).

```tsx
{/* Render any step */}
<WorkflowBody />

{/* Render only when the "review" step is active */}
<WorkflowBody stepId="review">
  <ReviewSummary />
</WorkflowBody>
```

<Callout title="Step-specific rendering">
  Use the `stepId` prop to conditionally render different layouts per step. When multiple `<WorkflowBody>` components are placed in the tree, only the one matching the current step (or the one without a `stepId`) will produce output.
</Callout>

***

WorkflowStepper [#workflowstepper]

Renders a progress indicator showing all **visible** steps. Steps hidden by conditions are automatically filtered out. The component maps between visible indices and original step indices so click handlers resolve to the correct step.

```tsx
import { WorkflowStepper } from '@rilaykit/workflow';
```

Props [#props-2]

| Prop          | Type                          | Required | Description                                                                                               |
| ------------- | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `onStepClick` | `(stepIndex: number) => void` | No       | Custom click handler. Receives the **original** step index. When omitted, clicking navigates to the step. |
| `className`   | `string`                      | No       | CSS class forwarded to the stepper renderer.                                                              |

The component delegates rendering to the `stepperRenderer` registered on your `ril` instance's workflow render config. The renderer receives:

```ts
interface WorkflowStepperRendererProps {
  steps: StepConfig[];           // Only visible steps
  currentStepIndex: number;      // Index within the visible steps array
  visitedSteps: Set<string>;     // Only visited steps that are currently visible
  onStepClick?: (index: number) => void;
  className?: string;
}
```

***

WorkflowNextButton [#workflownextbutton]

The primary action button. On intermediate steps it validates the form and advances. On the last visible step it validates and triggers `onWorkflowComplete`.

```tsx
import { WorkflowNextButton } from '@rilaykit/workflow';
```

Props [#props-3]

| Prop           | Type      | Required | Description                                                                                         |
| -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `isSubmitting` | `boolean` | No       | Override the submitting state. When omitted, the component derives it from form and workflow state. |
| `className`    | `string`  | No       | CSS class forwarded to the renderer.                                                                |

The component delegates rendering to `nextButtonRenderer`. The renderer receives:

```ts
interface WorkflowNextButtonRendererProps {
  isLastStep: boolean;
  canGoNext: boolean;
  isSubmitting: boolean;
  onSubmit: (event?: React.FormEvent) => void;
  currentStep: StepConfig;
  stepData: Record<string, unknown>;
  allData: Record<string, unknown>;
  context: WorkflowContext;
  className?: string;
}
```

`canGoNext` is `false` during transitions or when `isSubmitting` is `true`.

***

WorkflowPreviousButton [#workflowpreviousbutton]

Navigates to the previous visible step. Automatically accounts for hidden steps -- if the immediately previous step is invisible, it finds the next visible one before it.

```tsx
import { WorkflowPreviousButton } from '@rilaykit/workflow';
```

Props [#props-4]

| Prop           | Type      | Required | Description                          |
| -------------- | --------- | -------- | ------------------------------------ |
| `isSubmitting` | `boolean` | No       | Override the submitting state.       |
| `className`    | `string`  | No       | CSS class forwarded to the renderer. |

The component delegates rendering to `previousButtonRenderer`. The renderer receives:

```ts
interface WorkflowPreviousButtonRendererProps {
  canGoPrevious: boolean;
  isSubmitting: boolean;
  onPrevious: (event?: React.FormEvent) => void;
  currentStep: StepConfig;
  stepData: Record<string, unknown>;
  allData: Record<string, unknown>;
  context: WorkflowContext;
  className?: string;
}
```

`canGoPrevious` is `false` when on the first visible step, during transitions, or when submitting.

***

WorkflowSkipButton [#workflowskipbutton]

Allows the user to skip the current step without validation. The button is only actionable when the step has `allowSkip: true` or a `skippable` condition that evaluates to `true`.

```tsx
import { WorkflowSkipButton } from '@rilaykit/workflow';
```

Props [#props-5]

The component delegates rendering to `skipButtonRenderer`. The renderer receives:

```ts
interface WorkflowSkipButtonRendererProps {
  canSkip: boolean;
  isSubmitting: boolean;
  onSkip: (event?: React.FormEvent) => void;
  currentStep: StepConfig;
  stepData: Record<string, unknown>;
  allData: Record<string, unknown>;
  context: WorkflowContext;
  className?: string;
}
```

`canSkip` is `true` only when the step allows skipping and no transition or submission is in progress.

***

WorkflowProvider [#workflowprovider]

The internal context provider used by `<Workflow>`. You rarely need to use it directly, but it is exported for advanced composition patterns (e.g., wrapping with additional providers).

```tsx
import { WorkflowProvider } from '@rilaykit/workflow';
```

It manages:

* A **Zustand store** for workflow state (current step, collected data, visited/passed steps, loading flags).
* **FormProvider** synchronization -- re-mounts the form when the step changes, pre-populating fields with previously entered data.
* **Persistence** loading -- if a persistence adapter is configured, it loads saved state on mount.
* **Condition evaluation** -- determines step visibility and skip eligibility.
* **Analytics** tracking -- fires lifecycle events through the configured analytics callbacks.

Props [#props-6]

Same as `<Workflow>` except `workflowConfig` must be a built `WorkflowConfig` (not a builder).

***

Complete Example [#complete-example]

Here is a full layout putting all components together:

```tsx
import {
  Workflow,
  WorkflowBody,
  WorkflowStepper,
  WorkflowNextButton,
  WorkflowPreviousButton,
  WorkflowSkipButton,
} from '@rilaykit/workflow';

function OnboardingPage() {
  return (
    <Workflow
      workflowConfig={onboardingFlow}
      onWorkflowComplete={async (data) => {
        await api.completeOnboarding(data);
      }}
      className="max-w-2xl mx-auto"
    >
      {/* Progress bar */}
      <WorkflowStepper className="mb-8" />

{/* Step content */}
      <div className="min-h-[400px]">
        <WorkflowBody />
      </div>

{/* Navigation footer */}
      <div className="flex items-center justify-between mt-6 pt-4 border-t">
        <WorkflowPreviousButton className="px-4 py-2" />

<div className="flex gap-3">
          <WorkflowSkipButton className="px-4 py-2 text-muted-foreground" />
          <WorkflowNextButton className="px-6 py-2" />
        </div>
      </div>
    </Workflow>
  );
}
```

<Callout title="Renderer registration">
  All navigation components (`WorkflowStepper`, `WorkflowNextButton`, `WorkflowPreviousButton`, `WorkflowSkipButton`) require that you register corresponding renderers on your `ril` instance. Without a renderer, the component will render nothing. See the [Configuration](/docs/core-concepts/configuration) guide for details.
</Callout>

# Monitoring Adapters

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Adapters are the output layer of the monitoring system. Each adapter receives batches of `MonitoringEvent` objects and decides what to do with them -- log to the console, send to a remote API, persist in localStorage, etc. You can attach multiple adapters to a single `RilayMonitor` instance.

The MonitoringAdapter Interface [#the-monitoringadapter-interface]

Every adapter must implement the following interface:

```ts
interface MonitoringAdapter {
  name: string;
  send(events: MonitoringEvent[]): Promise<void>;
  flush?(): Promise<void>;
  configure?(config: Record<string, any>): void;
}
```

| Property            | Required | Description                                                                                      |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `name`              | Yes      | A unique identifier for the adapter. Used by `removeAdapter()`.                                  |
| `send(events)`      | Yes      | Receives a batch of events to process. Called automatically at each flush interval.              |
| `flush()`           | No       | Called when `monitor.flush()` is invoked. Use this to force-send any internally buffered events. |
| `configure(config)` | No       | Allows reconfiguring the adapter at runtime.                                                     |

Built-in Adapters [#built-in-adapters]

RilayKit ships with four adapters that cover the most common use cases.

ConsoleAdapter [#consoleadapter]

Logs events to the browser console. Useful during development or for quick debugging in production.

```ts
import { ConsoleAdapter } from '@rilaykit/core';

const adapter = new ConsoleAdapter('info');
monitor.addAdapter(adapter);
```

The constructor accepts an optional `logLevel` parameter that controls the minimum severity of events that are logged.

| Parameter  | Type                                     | Default  | Description                                                      |
| ---------- | ---------------------------------------- | -------- | ---------------------------------------------------------------- |
| `logLevel` | `'debug' \| 'info' \| 'warn' \| 'error'` | `'info'` | Minimum log level. Events below this level are silently ignored. |

RemoteAdapter [#remoteadapter]

Sends events to a remote HTTP endpoint. Events are batched and retried on failure, making this adapter suitable for production analytics pipelines.

```ts
import { RemoteAdapter } from '@rilaykit/core';

const adapter = new RemoteAdapter({
  endpoint: 'https://analytics.example.com/events',
  apiKey: 'your-api-key',
  headers: { 'X-App': 'my-app' },
  batchSize: 50,
  retryAttempts: 3,
});
monitor.addAdapter(adapter);
```

| Option          | Type                     | Default | Description                                                            |
| --------------- | ------------------------ | ------- | ---------------------------------------------------------------------- |
| `endpoint`      | `string`                 | --      | The URL to POST events to. **Required.**                               |
| `apiKey`        | `string`                 | --      | Sent as the `Authorization: Bearer` header value.                      |
| `headers`       | `Record<string, string>` | `{}`    | Additional HTTP headers to include in every request.                   |
| `batchSize`     | `number`                 | `50`    | Maximum number of events per request.                                  |
| `retryAttempts` | `number`                 | `3`     | Number of retry attempts on network failure before dropping the batch. |

<Callout type="info">
  The `RemoteAdapter` sends events as a JSON array in the request body. Each event conforms to the `MonitoringEvent` type. Your server should respond with a `2xx` status code to acknowledge receipt.
</Callout>

LocalStorageAdapter [#localstorageadapter]

Persists events in the browser's `localStorage`. This is useful for offline-first applications or for retaining events across page reloads before they can be flushed to a remote endpoint.

```ts
import { LocalStorageAdapter } from '@rilaykit/core';

const adapter = new LocalStorageAdapter(1000);
monitor.addAdapter(adapter);
```

| Parameter   | Type     | Default | Description                                                                                    |
| ----------- | -------- | ------- | ---------------------------------------------------------------------------------------------- |
| `maxEvents` | `number` | `1000`  | Maximum number of events to store. When the limit is reached, the oldest events are discarded. |

The adapter exposes additional methods for direct access to the stored data:

```ts
// Retrieve all stored events
const events = adapter.getStoredEvents();

// Get the current count
const count = adapter.getEventCount();

// Clear all stored events
adapter.clearStoredEvents();
```

<Callout>
  `LocalStorageAdapter` is intended for buffering or debugging. For long-term persistence, forward events to a remote endpoint using `RemoteAdapter`.
</Callout>

DevelopmentAdapter [#developmentadapter]

An enhanced console adapter designed for local development. It groups related events, color-codes severity levels, and prints periodic performance summaries.

```ts
import { DevelopmentAdapter } from '@rilaykit/core';

const adapter = new DevelopmentAdapter();
monitor.addAdapter(adapter);
```

No configuration is required. The adapter automatically formats output for readability:

* Events are grouped by source using `console.group`.
* Error events are highlighted with `console.error`.
* A performance summary is printed at each flush interval, showing average durations for tracked operations.

<Callout type="info">
  `DevelopmentAdapter` is a great default during local development. Swap it for `RemoteAdapter` in production. See the [Monitoring Overview](/docs/monitoring/overview) for a full setup example that switches adapters based on the environment.
</Callout>

Choosing the Right Adapter [#choosing-the-right-adapter]

<Tabs items={['Development', 'Staging', 'Production']}>
  <Tab value="Development">
    Use `DevelopmentAdapter` for rich, grouped console output with performance summaries.

```ts
    monitor.addAdapter(new DevelopmentAdapter());
    ```
  </Tab>

<Tab value="Staging">
    Combine `ConsoleAdapter` for visibility with `LocalStorageAdapter` for persistence across refreshes.

```ts
    monitor.addAdapter(new ConsoleAdapter('debug'));
    monitor.addAdapter(new LocalStorageAdapter(5000));
    ```
  </Tab>

<Tab value="Production">
    Use `RemoteAdapter` to send events to your analytics backend. Optionally add `LocalStorageAdapter` as a fallback buffer.

```ts
    monitor.addAdapter(new RemoteAdapter({
      endpoint: 'https://analytics.example.com/events',
      apiKey: process.env.MONITORING_API_KEY!,
      batchSize: 100,
      retryAttempts: 5,
    }));
    ```
  </Tab>
</Tabs>

Creating a Custom Adapter [#creating-a-custom-adapter]

You can create your own adapter by implementing the `MonitoringAdapter` interface. This is useful for integrating with third-party services like Sentry, Datadog, Mixpanel, or any proprietary system.

```ts title="lib/sentry-adapter.ts"
import type { MonitoringAdapter, MonitoringEvent } from '@rilaykit/core';
import * as Sentry from '@sentry/browser';

class SentryAdapter implements MonitoringAdapter {
  name = 'sentry';

async send(events: MonitoringEvent[]): Promise<void> {
    for (const event of events) {
      if (event.severity === 'critical' || event.severity === 'high') {
        Sentry.captureEvent({
          message: `[${event.type}] ${event.source}`,
          level: event.severity === 'critical' ? 'fatal' : 'error',
          extra: {
            data: event.data,
            metrics: event.metrics,
          },
          tags: {
            source: event.source,
            eventType: event.type,
          },
        });
      }
    }
  }

async flush(): Promise<void> {
    await Sentry.flush(2000);
  }
}
```

Then register it like any other adapter:

```ts
import { getGlobalMonitor } from '@rilaykit/core';
import { SentryAdapter } from '@/lib/sentry-adapter';

const monitor = getGlobalMonitor();
monitor?.addAdapter(new SentryAdapter());
```

Managing Adapters at Runtime [#managing-adapters-at-runtime]

Adapters can be added or removed at any time during the application lifecycle.

```ts
const monitor = getGlobalMonitor();

// Add an adapter
monitor?.addAdapter(new ConsoleAdapter('debug'));

// Remove it later by name
monitor?.removeAdapter('console');
```

This is useful for scenarios like enabling verbose logging when a user opens a debug panel, or temporarily attaching a `LocalStorageAdapter` to capture a reproduction of a bug.

# Monitoring Overview

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

RilayKit includes an optional monitoring system for tracking performance, errors, and user behavior across forms and workflows. The system is designed around a central `RilayMonitor` class that collects events and dispatches them to one or more **adapters** (console, remote endpoint, localStorage, etc.).

<Callout type="info">
  Monitoring is entirely opt-in. If you never call `initializeMonitoring`, no events are collected and there is zero runtime overhead.
</Callout>

Quick Setup [#quick-setup]

<Steps>
  <Step>
    1. Initialize the global monitor [#1-initialize-the-global-monitor]

Call `initializeMonitoring` once at application startup to create a singleton `RilayMonitor` instance.

```tsx
    import { initializeMonitoring, getGlobalMonitor, ConsoleAdapter } from '@rilaykit/core';

initializeMonitoring({
      enabled: true,
      sampleRate: 1.0,
      flushInterval: 30000,
    }, {
      appName: 'my-app',
      environment: 'production',
    });
    ```
  </Step>

<Step>
    2. Attach an adapter [#2-attach-an-adapter]

Adapters determine where events are sent. You can attach as many as you need.

```tsx
    const monitor = getGlobalMonitor();
    monitor?.addAdapter(new ConsoleAdapter('info'));
    ```
  </Step>

<Step>
    3. Start tracking [#3-start-tracking]

Once the monitor is initialized, RilayKit hooks (`useFormMonitoring`, `useWorkflowAnalytics`) automatically pick it up. You can also track custom events manually.

```tsx
    monitor?.track('custom', 'checkout-page', { action: 'coupon-applied' });
    ```
  </Step>
</Steps>

The RilayMonitor Class [#the-rilaymonitor-class]

`RilayMonitor` is the core of the monitoring system. It buffers events, manages adapters, and exposes a `PerformanceProfiler` for fine-grained timing.

```ts
class RilayMonitor {
  constructor(config: MonitoringConfig, context?: Partial<MonitoringContext>)

addAdapter(adapter: MonitoringAdapter): void
  removeAdapter(adapterName: string): void

track(
    type: MonitoringEventType,
    source: string,
    data: Record<string, any>,
    metrics?: PerformanceMetrics,
    severity?: 'low' | 'medium' | 'high' | 'critical',
  ): void
  trackError(error: Error, source: string, context?: any): void

getProfiler(): PerformanceProfiler
  updateContext(updates: Partial<MonitoringContext>): void

flush(): Promise<void>
  destroy(): Promise<void>
}
```

Key methods [#key-methods]

* **`track()`** -- Records a monitoring event of a given type (e.g. `'form_submit'`, `'validation_error'`, `'custom'`). Events are buffered and flushed to all attached adapters at the configured `flushInterval`.
* **`trackError()`** -- Convenience wrapper that creates an event with `severity: 'high'` and captures the error stack trace.
* **`flush()`** -- Immediately sends all buffered events to every adapter.
* **`destroy()`** -- Flushes remaining events and tears down internal timers. Call this on application unmount.

Global Monitoring [#global-monitoring]

For convenience, RilayKit provides three functions to manage a global singleton so you don't need to pass the monitor instance around manually.

| Function                                 | Description                                                       |
| ---------------------------------------- | ----------------------------------------------------------------- |
| `initializeMonitoring(config, context?)` | Creates and stores a global `RilayMonitor` singleton.             |
| `getGlobalMonitor()`                     | Returns the current global monitor, or `null` if not initialized. |
| `destroyGlobalMonitoring()`              | Calls `destroy()` on the global monitor and clears the reference. |

```tsx
import {
  initializeMonitoring,
  getGlobalMonitor,
  destroyGlobalMonitoring,
} from '@rilaykit/core';

// At app startup
initializeMonitoring({
  enabled: true,
  sampleRate: 0.5, // sample 50% of events
  flushInterval: 15000,
}, {
  appName: 'my-app',
  environment: 'staging',
});

// Anywhere in the app
const monitor = getGlobalMonitor();
monitor?.track('custom', 'dashboard', { widget: 'revenue-chart' });

// At app teardown
await destroyGlobalMonitoring();
```

PerformanceProfiler [#performanceprofiler]

Every `RilayMonitor` instance includes a `PerformanceProfiler` accessible via `getProfiler()`. Use it to instrument specific code paths with high-resolution timing.

```ts
const profiler = monitor.getProfiler();

profiler.start('data-fetch');
const data = await fetchData();
profiler.end('data-fetch');

// Or use marks and measures for more complex timings
profiler.mark('render-start');
// ... rendering logic ...
profiler.mark('render-end');
profiler.measure('full-render', 'render-start', 'render-end');

// Retrieve all collected metrics
const metrics = profiler.getMetrics();
```

| Method                               | Description                              |
| ------------------------------------ | ---------------------------------------- |
| `.start(label)`                      | Starts a timer with the given label.     |
| `.end(label)`                        | Ends the timer and records the duration. |
| `.mark(name)`                        | Places a named timestamp mark.           |
| `.measure(name, startMark, endMark)` | Measures the duration between two marks. |
| `.getMetrics()`                      | Returns all recorded timing data.        |

Integration with Forms [#integration-with-forms]

The `useFormMonitoring` hook from `@rilaykit/forms` provides automatic tracking for common form lifecycle events. It connects to the global monitor internally.

```tsx
import { useFormMonitoring } from '@rilaykit/forms';

const {
  trackFormRender,
  trackFormValidation,
  trackFormSubmission,
  trackFieldChange,
  startPerformanceTracking,
  endPerformanceTracking,
} = useFormMonitoring({
  formConfig,
  monitoring,
  enabled: true,
});
```

<Callout>
  You don't need to call these methods manually in most cases. The `<Form>` and `<FormField>` components invoke them automatically when a global monitor is active.
</Callout>

What is tracked automatically [#what-is-tracked-automatically]

* **Form render** -- Time to first meaningful paint for each form.
* **Field changes** -- Which fields are modified and how often.
* **Validation** -- Validation duration, pass/fail counts, and error messages.
* **Submission** -- Submission attempts, success/failure, and total time.

Integration with Workflows [#integration-with-workflows]

The `useWorkflowAnalytics` hook from `@rilaykit/workflow` leverages the global monitor internally to track workflow-specific events.

Tracked events include:

* Step navigation (forward, backward, skip)
* Step completion time
* Abandonment rate per step
* Overall workflow completion

<Callout type="info">
  Workflow analytics are collected automatically when a global monitor is initialized. No additional setup is required beyond calling `initializeMonitoring`.
</Callout>

Complete Example [#complete-example]

Here is a full example that initializes monitoring in a Next.js application with multiple adapters.

```tsx title="lib/monitoring.ts"
import {
  initializeMonitoring,
  getGlobalMonitor,
  ConsoleAdapter,
  RemoteAdapter,
  DevelopmentAdapter,
} from '@rilaykit/core';

export function setupMonitoring() {
  const isDev = process.env.NODE_ENV === 'development';

initializeMonitoring({
    enabled: true,
    sampleRate: isDev ? 1.0 : 0.25,
    flushInterval: isDev ? 5000 : 30000,
  }, {
    appName: 'my-saas',
    environment: isDev ? 'development' : 'production',
  });

const monitor = getGlobalMonitor();
  if (!monitor) return;

if (isDev) {
    monitor.addAdapter(new DevelopmentAdapter());
  } else {
    monitor.addAdapter(new RemoteAdapter({
      endpoint: 'https://analytics.example.com/events',
      apiKey: process.env.MONITORING_API_KEY!,
      batchSize: 50,
      retryAttempts: 3,
    }));
  }
}
```

```tsx title="app/layout.tsx"
import { setupMonitoring } from '@/lib/monitoring';

// Initialize once at the root
setupMonitoring();

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html><body>{children}</body></html>;
}
```

Core

Forms

Workflow

Contact Us

Sign In

Style It

Add Logic

Multi-Step

Validate

User Details

Items ({count})