Formity Documentation

The s.Switch abstraction allows you to create multi-step forms that branch into different paths based on previous user input.

To use it, define a switch object within your Flow array. A switch consists of:

1. branches: An array of branch objects. Each branch contains:
   • case: A predicate function that receives the current form state and returns true if the branch should be taken.
   • then: An array of steps (e.g., form or return) to execute if the case matches.
2. default: An array of steps to execute if none of the branches match the current state.

This pattern is useful for complex logic where the next set of questions depends entirely on a previous answer (e.g., asking "Why not?" if a user selects "No").

import type { s } from "@formity/react";

// Example structure within a Flow definition
const myFlow = [
  {
    form: { /* initial step */ }
  },
  {
    switch: {
      branches: [
        {
          case: ({ choice }) => choice === 'yes',
          then: [
            { form: { /* step for 'yes' path */ } },
            { return: (data) => ({ choice: 'yes', reason: data.reason }) }
          ]
        }
      ],
      default: [
        { form: { /* fallback step */ } },
        { return: (data) => ({ choice: 'unknown', reason: data.reason }) }
      ]
    }
  }
];

You can implement iterative logic within a Flow using the loop property. A loop requires a while condition and a do array of steps to execute in each iteration.

Inside the while condition, you have access to the current state of variables. The do array can contain steps that update variables, render forms, or perform other logic. To maintain state across iterations (like an index or an accumulator), you must explicitly update those variables in a step within the do block.

Common patterns include:

1. Condition: Using a while function that checks a variable (e.g., i < list.length).
2. Iteration Step: Using a variables step to extract the current item from a list based on the index.
3. Form Step: Using a form step to collect data for the current iteration.
4. Update Step: Using a variables step at the end of the do block to increment the index and append the new data to an accumulator array.

export const loopFlow: Flow<LoopSchema> = [
  // 1. Initialize variables
  { variables: () => ({ i: 0, results: [] }) },
  
  // 2. Define the loop
  { 
    loop: {
      while: ({ i, items }) => i < items.length,
      do: [
        // Step A: Set current item context
        { variables: ({ i, items }) => ({ currentItem: items[i] }) },
        
        // Step B: Render the form for this item
        { 
          form: {
            fields: ({ currentItem }) => ({ value: ["field", [currentItem.id]] }),
            render: ({ fields, values }) => (
              <Form {...fields}>
                {/* Your UI components */}
              </Form>
            )
          }
        },

        // Step C: Update index and accumulator
        { 
          variables: ({ i, results, currentItem, value }) => ({
            i: i + 1,
            results: [...results, { id: currentItem.id, value }]
          })
        }
      ]
    }
  },

  // 3. Return final results
  { return: ({ results }) => ({ results }) }
];

Formity uses a declarative Flow structure to define multi-step forms. A Flow is an array of step objects that can include forms, conditional logic, loops, variable management, and data yielding.

Each step in the struct array defines a specific part of the user journey. Common step types include:

• s.Form: Renders a form with specific fields and validation.
• s.Yield: Defines how data is passed forward (next) or backward (back) between steps.
• s.Condition: Branches the flow based on existing data using then and else arrays.
• s.Variables: Manages local state/variables within a branch of the flow.
• s.Loop: Repeats a sequence of steps based on a while condition.
• s.Return: Finalizes the flow by transforming accumulated data into a final result object.

To use this, you define a Schema type that describes the shape of the data at each step and then implement the flow array.

import type { Flow, s } from "@formity/react";

type Schema = {
  struct: [
    s.Form<{ name: string }>,
    s.Yield<{ next: [{ type: 'next'; data: { name: string } }]; back: [{ type: 'back'; data: { name: string } }]; }>,
    s.Return<{ name: string }>
  ];
  // ...
};

export const flow: Flow<Schema> = [
  {
    form: {
      fields: () => ({ name: ["", []] }),
      render: ({ fields, ...rest }) => (
        <Form defaultValues={fields} ...>
          <TextField name="name" ... />
        </Form>
      )
    }
  },
  // ...
];

You can create multi-step logic in a Flow using the s.Condition structure. A condition block evaluates a predicate function (if) and branches the form flow into either a then array or an else array based on the result.

• if: A function that receives the current form state and returns a boolean.
• then: An array of steps to execute if the condition is true. This typically includes a form step followed by a return step to merge the new data into the main state.
• else: An array of steps to execute if the condition is false.
• return: A step used within a branch to map the local branch data back into the global form schema.

This pattern allows for complex, nested logic where the final data object is a composition of the paths taken through the flow.

import type { Flow, s } from "@formity/react";

export const conditionFlow: Flow<ConditionSchema> = [
  {
    form: {
      fields: () => ({ softwareDeveloper: [true, []] }),
      render: ({ fields, ...rest }) => (
        <Form ... />
      ),
    },
  },
  {
    condition: {
      if: ({ softwareDeveloper }) => softwareDeveloper,
      then: [
        {
          form: {
            fields: () => ({ languages: [[], []] }),
            render: ({ fields, ...rest }) => (
              <Form ... />
            ),
          },
        },
        {
          return: ({ languages }) => ({
            softwareDeveloper: true,
            languages,
          }),
        },
      ],
      else: [
        {
          form: {
            fields: () => ({ interested: ["maybe", []] }),
            render: ({ fields, ...rest }) => (
              <Form ... />
            ),
          },
        },
        {
          return: ({ interested }) => ({
            softwareDeveloper: false,
            interested,
          }),
        },
      ],
    },
  },
];

Formity uses two primary high-level types to define the structure and behavior of multi-step forms and modules. These types leverage TypeScript's type inference to map the form's structure (struct) to the data available during rendering.

Flow<T>

Used for a standalone multi-step form. It is derived from a Schema and determines the rendered output based on:

• render: The type of the rendered output for each step.
• struct: The structural definition of the form steps.
• inputs: Values provided via the inputs prop.
• params: Contextual values accessible during rendering.

Module<T>

Used for a reusable multi-step form module. It is derived from a ModuleSchema and includes an additional property:

• values: The values collected throughout the module's lifecycle.

Both types ensure that the data passed to rendering functions (like fields, variables, or condition checks) is strictly typed based on the form's structure.