Formity

https://formity.app/docs
Admin
Formity is an advanced form-building package for React developers that creates multi-step forms with...
Tokens:57,708
Snippets:245
Trust Score:6.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Clone Repository

Source: https://formity.app/docs/guides/review-step

Clone the repository to get started with the review step example.

```bash
git clone https://github.com/martiserra99/formity-review-step

```

--------------------------------

### Clone Formity Repository

Source: https://formity.app/docs/guides/state-outside-the-form

Clone the example repository to follow along with the guide. This sets up the project structure for the demonstration.

```bash
git clone https://github.com/martiserra99/formity-state-outside-the-form

```

--------------------------------

### Install Dependencies

Source: https://formity.app/docs/guides/repeating-steps

Install the necessary project dependencies after cloning the repository.

```bash
npm install

```

--------------------------------

### Basic Formity Component Setup

Source: https://formity.app/docs/getting-started/tutorial

This snippet shows the initial setup of the Formity component in an app.tsx file. It includes necessary imports and the basic structure for rendering a multi-step form with a return callback.

```tsx
// app.tsx
import { useCallback, useState } from "react";

import {
  Formity,
  type Flow,
  type OnReturn,
  type ReturnOutput,
} from "@formity/react";

import { Output } from "./components/output";

type Schema = {
  render: React.ReactNode;
  struct: [];
  inputs: Record<never, never>;
  params: Record<never, never>;
};

const flow: Flow<Schema> = [];

export default function App() {
  const [output, setOutput] = useState<ReturnOutput<Schema> | null>(null);

  const onReturn = useCallback<OnReturn<Schema>>((output) => {
    setOutput(output);
  }, []);

  if (output) {
    return <Output output={output} onStartOver={() => setOutput(null)} />;
  }

  return <Formity<Schema> flow={flow} onReturn={onReturn} />;
}

```

--------------------------------

### Workspace Setup Form

Source: https://formity.app/docs/guides/sidebar-navigation

Configures the fields and rendering for the workspace setup step, including workspace name, timezone, and language.

```javascript
{
    jump: {
      id: workspace.id,
      at: {
        form: {
          fields: () => ({
            workspaceName: [values.workspaceName, []],
            timezone: [values.timezone, []],
            language: [values.language, []],
          }),
          render: ({ fields, params, next, jump }) => ({
            step: 2,
            form: (
              <Form
                key={workspace.id}
                defaultValues={fields}
                validate={workspace.zod}
                heading="Set up your workspace"
                message="Give your workspace a name and configure your region."
                content={[
                  {
                    type: "input",
                    name: "workspaceName",
                    label: "Workspace name",
                    placeholder: "My Workspace",
                  },
                  {
                    type: "select",
                    name: "timezone",
                    label: "Timezone",
                    placeholder: "Select a timezone",
                    options: constants.timezones,
                  },
                  {
                    type: "select",
                    name: "language",
                    label: "Language",
                    placeholder: "Select a language",
                    options: constants.languages,
                  },
                ])}
                buttons={{ back: "Back", next: "Continue" }}
                next={next}
                jump={jump}
                prev={company.id}
                values={params.values}
                onValuesChange={params.onValuesChange}
              />
            ),
          }),
        },
      },
    },
  }
```

--------------------------------

### Install Motion Library

Source: https://formity.app/docs/guides/animating-forms

Install the Motion library, which will be used for implementing animations in the form. This is a required dependency for animating forms.

```bash
npm install motion

```

--------------------------------

### Profile Setup Form

Source: https://formity.app/docs/guides/sidebar-navigation

Configures the fields and rendering for the initial profile setup step, including name, email, and job title.

```javascript
{
    jump: {
      id: profile.id,
      at: {
        form: {
          fields: () => ({ name: "", email: "", jobTitle: "" }),
          render: ({ fields, params, next, jump }) => ({
            step: 1,
            form: (
              <Form
                key={profile.id}
                defaultValues={fields}
                validate={profile.zod}
                heading="Set up your profile"
                message="Give your workspace a name and configure your region."
                content={[
                  {
                    type: "input",
                    name: "name",
                    label: "Full name",
                    placeholder: "Alex Johnson",
                  },
                  {
                    type: "input",
                    name: "email",
                    label: "Work email",
                    placeholder: "alex.j@example.com",
                  },
                  {
                    type: "input",
                    name: "jobTitle",
                    label: "Job title",
                    placeholder: "Product Manager",
                  },
                  {
                    type: "input",
                    name: "companyName",
                    label: "Company name",
                    placeholder: "Acme Inc.",
                  },
                  {
                    type: "select",
                    name: "industry",
                    label: "Industry",
                    placeholder: "Select an industry",
                    options: constants.industries,
                  },
                  {
                    type: "select",
                    name: "companySize",
                    label: "Company size",
                    placeholder: "Select a size",
                    options: constants.companySizes,
                  },
                ])}
                buttons={{ back: "Back", next: "Continue" }}
                next={next}
                jump={jump}
                prev={profile.id}
                values={params.values}
                onValuesChange={params.onValuesChange}
              />
            ),
          }),
        },
      },
    },
  }
```

--------------------------------

### Install Dependencies

Source: https://formity.app/docs/use-with-form-libraries/formik

After cloning the repository, install the necessary project dependencies using npm. This command ensures all required packages are available for the integration to work.

```bash
npm install
```

--------------------------------

### Install Formity

Source: https://formity.app/docs/getting-started/introduction

Install the Formity React library using npm. This command adds the necessary package to your project's dependencies.

```bash
npm install @formity/react

```

--------------------------------

### Clone Formity Tutorial Repository

Source: https://formity.app/docs/getting-started/tutorial

Clone the Formity tutorial repository to follow along with the setup process.

```bash
git clone https://github.com/martiserra99/formity-tutorial

```

--------------------------------

### Formity Module Structure Example

Source: https://formity.app/docs/guides/using-modules

This example demonstrates the basic structure of a Formity module, including conditional logic and form rendering.

```javascript
const flow = [
  {
    module: [
      {
        condition: {
          if: ({ softwareDeveloper }) => softwareDeveloper === "yes",
          then: [
            {
              form: {
                fields: () => ({
                  expertise: ["", []],
                }),
                render: ({ fields, params, back, next }) => (
                  <Form
                    key="expertise"
                    defaultValues={fields}
                    resolver={zodResolver(
                      z.object({
                        expertise: z.string().nonempty("Required"),
                      }),
                    )}
                    heading="What is your area of expertise?"
                    content={[
                      {
                        type: "select",
                        name: "expertise",
                        label: "Expertise",
                        placeholder: "Select an option",
                        options: [
                          { value: "frontend", label: "Frontend development" },
                          { value: "backend", label: "Backend development" },
                          { value: "mobile", label: "Mobile development" },
                        ],
                      },
                    ]}
                    buttons={{
                      back: "Back",
                      next: "Submit",
                    }}
                    back={back}
                    next={next}
                    status={params.status}
                  />
                ),
              },
            },
            {
              return: ({ name, surname, age, expertise }) => ({
                name,
                surname,
                age,
                softwareDeveloper: true,
                expertise,
              }),
            },
          ],
          else: [
            {
              form: {
                fields: () => ({
                  interested: ["", []],
                }),
                render: ({ fields, params, back, next }) => (
                  <Form
                    key="interested"
                    defaultValues={fields}
                    resolver={zodResolver(
                      z.object({
                        interested: z.string().nonempty("Required"),
                      }),
                    )}
                    heading="Are you interested in learning how to code?"
                    content={[
                      {
                        type: "select",
                        name: "interested",
                        label: "Interested",
                        placeholder: "Select an option",
                        options: [
                          { value: "yes", label: "Yes, I am interested." },
                          { value: "no", label: "No, it is not for me." },
                          { value: "maybe", label: "Maybe, I am not sure." },
                        ],
                      },
                    ]}
                    buttons={{
                      back: "Back",
                      next: "Submit",
                    }}
                    back={back}
                    next={next}
                    status={params.status}
                  />
                ),
              },
            },
            {
              return: ({ name, surname, age, interested }) => ({
                name,
                surname,
                age,
                softwareDeveloper: false,
                interested,
              }),
            },
          ],
        },
      },
    ],
  },
];

export default function App() {
  const [status, setStatus] = useState<Status<ReturnOutput<Schema>>>({ 
    type: "form",
    submitting: false,
  });

  const onReturn = useCallback<OnReturn<Schema>>(async (output) => {
    setStatus({ type: "form", submitting: true });

    // Show output in the console
    console.log(output);

    // Simulate a network request
    await new Promise((resolve) => setTimeout(resolve, 1000));

    setStatus({ type: "done", output });
  }, []);

  if (status.type === "done") {
    return (
      <Done
        output={status.output}
        onStartOver={() => setStatus({ type: "form", submitting: false })}
      />
    );
  }

  return (
    <Formity<Schema> flow={flow} params={{ status }} onReturn={onReturn} />
  );
}

```

--------------------------------

### Clone TanStack Form Integration Repository

Source: https://formity.app/docs/use-with-form-libraries/tanstack-form

Clone the official repository to get started with the Formity and TanStack Form integration. This is the first step to setting up the integration.

```bash
git clone https://github.com/martiserra99/formity-tanstack-form
```

--------------------------------

### Clone Formity React Hook Form Repository

Source: https://formity.app/docs/use-with-form-libraries/react-hook-form

Clone the official repository to get started with the integration example.

```bash
git clone https://github.com/martiserra99/formity-react-hook-form
```

--------------------------------

### App Component Setup for Formity

Source: https://formity.app/docs/guides/animating-forms

This snippet shows the basic setup for the main application component, including necessary imports for Formity, React Hook Form, and Zod validation.

```tsx
// app.tsx
import { useCallback, useState } from "react";

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

import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

import type { Status, FormStatus } from "./types/status";

import { Form } from "./components/form";
import { Done } from "./components/done";


```

--------------------------------

### Clone Formity Formik Repository

Source: https://formity.app/docs/use-with-form-libraries/formik

Clone the official repository to access the Formity and Formik integration example. This is the first step to setting up the integration.

```bash
git clone https://github.com/martiserra99/formity-formik
```

--------------------------------

### Clone Formity Sidebar Navigation Repository

Source: https://formity.app/docs/guides/sidebar-navigation

Clone the repository to follow along with the guide. This sets up the initial project structure.

```bash
git clone https://github.com/martiserra99/formity-sidebar-navigation

```

--------------------------------

### Workspace Setup Form Fields

Source: https://formity.app/docs/guides/sidebar-navigation

Defines the input fields for creating a new workspace, including name, timezone, and language selection.

```javascript
{
                  type: "input",
                  name: "workspaceName",
                  label: "Workspace name",
                  placeholder: "My Workspace",
                },
                {
                  type: "select",
                  name: "timezone",
                  label: "Timezone",
                  placeholder: "Select a timezone",
                  options: constants.timezones,
                },
                {
                  type: "select",
                  name: "language",
                  label: "Language",
                  placeholder: "Select a language",
                  options: constants.languages,
                },
              ]}
```

--------------------------------

### Basic useFormity Hook Usage

Source: https://formity.app/docs/basic-concepts/use-formity

Demonstrates the fundamental setup of the useFormity hook with a defined schema, flow, and an onReturn callback. This is the primary way to initialize a multi-step form.

```tsx
type Schema = {
  render: { step: number; form: ReactNode };
  struct: [s.Form<{ name: string }>, s.Return<{ name: string }>];
  inputs: Record<never, never>;
  params: Record<never, never>;
};

const flow: Flow<Schema> = [
  {
    form: {
      fields: () => ({
        name: ["", []],
      }),
      render: ({ fields, next }) => ({
        step: 0,
        form: <AboutMeForm fields={fields} next={next} />,
      }),
    },
  },
  {
    return: ({ name }) => ({ name }),
  },
];

const { step, form } = useFormity<Schema>({ flow, onReturn });

```

--------------------------------

### Review Jump Configuration

Source: https://formity.app/docs/guides/sidebar-navigation

This snippet shows the basic structure for configuring a 'jump' action for a review section, indicating the start of a new jump configuration.

```javascript
jump: {
      id: review.id,
      at: {
        form: {

```

--------------------------------

### Single-Step Form Example with React Hook Form

Source: https://formity.app/docs/getting-started/tutorial

This example demonstrates a single-step form built with React Hook Form. Formity is designed to be compatible with various single-step form libraries.

```tsx
// app.tsx
import { useCallback, useState } from "react";

import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

import { Form } from "./components/form";
import { Output } from "./components/output";

type Values = { name: string; surname: string; age: number };

export default function App() {
  const [output, setOutput] = useState<Values | null>(null);

  const onSubmit = useCallback((output: Values) => {
    setOutput(output);
  }, []);

  if (output) {
    return <Output output={output} onStartOver={() => setOutput(null)} />;
  }

  return (
    <Form
      defaultValues={{
        name: "",
        surname: "",
        age: 20,
      }}
      resolver={zodResolver(
        z.object({
          name: z.string().nonempty("Required"),
          surname: z.string().nonempty("Required"),
          age: z.number().min(18, "Min. 18").max(99, "Max. 99"),
        }),
      )}
      heading="Tell us about yourself"
      content={[
        {
          type: "columns",
          columns: [
            {
              type: "input",
              name: "name",
              label: "Name",
              placeholder: "Your name",
            },
            {
              type: "input",
              name: "surname",
              label: "Surname",
              placeholder: "Your surname",
            },
          ],
        },
        {
          type: "number",
          name: "age",
          label: "Age",
          placeholder: "Your age",
        },
      ]}
      submit="Submit"
      onSubmit={onSubmit}
    />
  );
}


```

--------------------------------

### Form with Progress Bar and Animation

Source: https://formity.app/docs/guides/animating-forms

This example shows a multi-step form where each step returns progress information. It uses `motion` for animations and `zod` for validation. The `Form` component is a custom component that accepts status and setStatus props for managing form state.

```tsx
import { useCallback, useState } from "react";

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

import { motion } from "motion/react";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

import type { Status, FormStatus } from "./types/status";

import { Form } from "./components/form";
import { Done } from "./components/done";

type Schema = {
  render: {
    progress: {
      numberSteps: number;
      currentStep: number;
    };
    form: React.ReactNode;
  };
  struct: [
    s.Form<{ name: string; surname: string; age: number }>,
    s.Form<{ softwareDeveloper: string }>,
    s.Condition<{
      then: [
        s.Form<{ expertise: string }>,
        s.Return<{
          name: string;
          surname: string;
          age: number;
          softwareDeveloper: true;
          expertise: string;
        }>,
      ];
      else: [
        s.Form<{ interested: string }>,
        s.Return<{
          name: string;
          surname: string;
          age: number;
          softwareDeveloper: false;
          interested: string;
        }>,
      ];
    }>,
  ];
  inputs: Record<never, never>;
  params: {
    status: FormStatus;
    setStatus: (status: FormStatus) => void;
  };
};

const flow: Flow<Schema> = [
  {
    form: {
      fields: () => ({
        name: ["", []],
        surname: ["", []],
        age: [20, []],
      }),
      render: ({ fields, params, back, next }) => ({
        progress: {
          numberSteps: 3,
          currentStep: 1,
        },
        form: (
          <Form
            id="yourself"
            defaultValues={fields}
            resolver={zodResolver(
              z.object({
                name: z.string().nonempty("Required"),
                surname: z.string().nonempty("Required"),
                age: z.number().min(18, "Min. 18").max(99, "Max. 99"),
              }),
            )}
            heading="Tell us about yourself"
            content={[ 
              {
                type: "columns",
                columns: [
                  {
                    type: "input",
                    name: "name",
                    label: "Name",
                    placeholder: "Your name",
                  },
                  {
                    type: "input",
                    name: "surname",
                    label: "Surname",
                    placeholder: "Your surname",
                  },
                ],
              },
              {
                type: "number",
                name: "age",
                label: "Age",
                placeholder: "Your age",
              },
            ]}
            buttons={{
              back: null,
              next: "Next",
            }}
            back={back}
            next={next}
            status={params.status}
            setStatus={params.setStatus}
          />
        ),
      }),
    },
  },
  {
    form: {
      fields: () => ({
        softwareDeveloper: ["", []],
      }),
      render: ({ fields, params, back, next }) => ({
        progress: {
          numberSteps: 3,
          currentStep: 2,
        },
        form: (
          <Form
            id="softwareDeveloper"
            defaultValues={fields}
            resolver={zodResolver(
              z.object({
                softwareDeveloper: z.string().nonempty("Required"),
              }),
            )}
            heading="Are you a software developer?"
            content={[ 
              {
                type: "select",
                name: "softwareDeveloper",
                label: "Software Developer",
                placeholder: "Select an option",
                options: [
                  { value: "yes", label: "Yes" },
                  { value: "no", label: "No" },
                ],
              },
            ]}
            buttons={{
              back: "Back",
              next: "Next",
            }}
            back={back}
            next={next}
            status={params.status}
            setStatus={params.setStatus}
          />
        ),
      }),
    },
  },
  {
    condition: {
      if: ({ softwareDeveloper }) => softwareDeveloper === "yes",
      then: [
        {
          form: {
            fields: () => ({
              expertise: ["", []],
            }),
            render: ({ fields, params, back, next }) => ({
              progress: {
                numberSteps: 3,
                currentStep: 3,
              },
              form: (
                <Form
                  id="expertise"
                  defaultValues={fields}
                  resolver={zodResolver(
                    z.object({
                      expertise: z.string().nonempty("Required"),
                    }),
                  )}

```

--------------------------------

### Defining a Multi-step Form Flow

Source: https://formity.app/docs/getting-started/tutorial

This example demonstrates how to define a multi-step form's structure and behavior using the `flow` object. It includes two steps: collecting personal information and asking about software development status, with validation using Zod.

```tsx
// app.tsx
import { useCallback, useState } from "react";

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

import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

import { Form } from "./components/form";
import { Output } from "./components/output";

type Schema = {
  render: React.ReactNode;
  struct: [
    s.Form<{ name: string; surname: string; age: number }>,
    s.Form<{ softwareDeveloper: string }>,
  ];
  inputs: Record<never, never>;
  params: Record<never, never>;
};

const flow: Flow<Schema> = [
  {
    form: {
      fields: () => ({
        name: ["", []],
        surname: ["", []],
        age: [20, []],
      }),
      render: ({ fields, next }) => (
        <Form
          key="yourself"
          defaultValues={fields}
          resolver={zodResolver(
            z.object({
              name: z.string().nonempty("Required"),
              surname: z.string().nonempty("Required"),
              age: z.number().min(18, "Min. 18").max(99, "Max. 99"),
            }),
          )}
          heading="Tell us about yourself"
          content={[
            {
              type: "columns",
              columns: [
                {
                  type: "input",
                  name: "name",
                  label: "Name",
                  placeholder: "Your name",
                },
                {
                  type: "input",
                  name: "surname",
                  label: "Surname",
                  placeholder: "Your surname",
                },
              ],
            },
            {
              type: "number",
              name: "age",
              label: "Age",
              placeholder: "Your age",
            },
          ]}
          submit="Next"
          onSubmit={next}
        />
      ),
    },
  },
  {
    form: {
      fields: () => ({
        softwareDeveloper: ["", []],
      }),
      render: ({ fields, next }) => (
        <Form
          key="softwareDeveloper"
          defaultValues={fields}
          resolver={zodResolver(
            z.object({
              softwareDeveloper: z.string().nonempty("Required"),
            }),
          )}
          heading="Are you a software developer?"
          content={[
            {
              type: "select",
              name: "softwareDeveloper",
              label: "Software Developer",
              placeholder: "Select an option",
              options: [
                { value: "yes", label: "Yes" },
                { value: "no", label: "No" },
              ],
            },
          ]}
          submit="Next"
          onSubmit={next}
        />
      ),
    },
  },
];

export default function App() {
  const [output, setOutput] = useState<ReturnOutput<Schema> | null>(null);

  const onReturn = useCallback<OnReturn<Schema>>((output) => {
    setOutput(output);
  }, []);

  if (output) {
    return <Output output={output} onStartOver={() => setOutput(null)} />;
  }

  return <Formity<Schema> flow={flow} onReturn={onReturn} />;
}

```

--------------------------------

### Multi-step Form with Form and Return Elements

Source: https://formity.app/docs/getting-started/tutorial

This snippet shows a complete multi-step form implementation using Formity. It includes two form steps for collecting user information and a return step to process the collected data. Ensure you have the necessary Formity and Zod dependencies installed.

```tsx
// app.tsx
import { useCallback, useState } from "react";

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

import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

import { Form } from "./components/form";
import { Output } from "./components/output";

type Schema = {
  render: React.ReactNode;
  struct: [
    s.Form<{ name: string; surname: string; age: number }>,
    s.Form<{ softwareDeveloper: string }>,
    s.Return<{
      name: string;
      surname: string;
      age: number;
      softwareDeveloper: string;
    }>,
  ];
  inputs: Record<never, never>;
  params: Record<never, never>;
};

const flow: Flow<Schema> = [
  {
    form: {
      fields: () => ({
        name: ["", []],
        surname: ["", []],
        age: [20, []],
      }),
      render: ({ fields, next }) => (
        <Form
          key="yourself"
          defaultValues={fields}
          resolver={zodResolver(
            z.object({
              name: z.string().nonempty("Required"),
              surname: z.string().nonempty("Required"),
              age: z.number().min(18, "Min. 18").max(99, "Max. 99"),
            }),
          )}
          heading="Tell us about yourself"
          content={[
            {
              type: "columns",
              columns: [
                {
                  type: "input",
                  name: "name",
                  label: "Name",
                  placeholder: "Your name",
                },
                {
                  type: "input",
                  name: "surname",
                  label: "Surname",
                  placeholder: "Your surname",
                },
              ],
            },
            {
              type: "number",
              name: "age",
              label: "Age",
              placeholder: "Your age",
            },
          ]}
          submit="Next"
          onSubmit={next}
        />
      ),
    },
  },
  {
    form: {
      fields: () => ({
        softwareDeveloper: ["", []],
      }),
      render: ({ fields, next }) => (
        <Form
          key="softwareDeveloper"
          defaultValues={fields}
          resolver={zodResolver(
            z.object({
              softwareDeveloper: z.string().nonempty("Required"),
            }),
          )}
          heading="Are you a software developer?"
          content={[
            {
              type: "select",
              name: "softwareDeveloper",
              label: "Software Developer",
              placeholder: "Select an option",
              options: [
                { value: "yes", label: "Yes" },
                { value: "no", label: "No" },
              ],
            },
          ]}
          submit="Next"
          onSubmit={next}
        />
      ),
    },
  },
  {
    return: ({ name, surname, age, softwareDeveloper }) => ({
      name,
      surname,
      age,
      softwareDeveloper,
    }),
  },
];

export default function App() {
  const [output, setOutput] = useState<ReturnOutput<Schema> | null>(null);

  const onReturn = useCallback<OnReturn<Schema>>((output) => {
    setOutput(output);
  }, []);

  if (output) {
    return <Output output={output} onStartOver={() => setOutput(null)} />;
  }

  return <Formity<Schema> flow={flow} onReturn={onReturn} />;
}

```

--------------------------------

### Review and Launch Form

Source: https://formity.app/docs/guides/sidebar-navigation

Renders the review step, displaying summarized user inputs from profile, company, and workspace sections before launching.

```javascript
{
    jump: {
      id: review.id,
      at: {
        form: {
          fields: () => ({}),
          render: ({ values, params, next, jump }) => ({
            step: 3,
            form: (
              <Review
                key={review.id}
                heading="Review & launch"
                message="Everything look right? Launch your workspace."
                content={[
                  {
                    text: "Profile",
                    rows: [
                      { label: "Full name", value: format.text(values.name) },
                      { label: "Work email", value: format.text(values.email) },
                      {
                        label: "Job title",
                        value: format.text(values.jobTitle),
                      },
                    ],
                  },
                  {
                    text: "Company",
                    rows: [
                      {
                        label: "Company name",
                        value: format.text(values.companyName),
                      },
                      {
                        label: "Industry",
                        value: format.industry(values.industry),
                      },
                      {
                        label: "Company size",
                        value: format.companySize(values.companySize),
                      },
                    ],
                  },
                  {
                    text: "Workspace",
                    rows: [
                      {
                        label: "Workspace name",
                        value: format.text(values.workspaceName),
                      },
                      {
                        label: "Timezone",
                        value: format.timezone(values.timezone),
                      },
                      {
                        label: "Language",
                        value: format.language(values.language),
                      },
                    ],
                  },
                ]}
                buttons={{ back: "Back", next: "Launch workspace" }}
                next={next}
                jump={jump}
                prev={workspace.id}
              />
            ),
          }),
        },
      },
    },
  }
```

--------------------------------

### Review and Launch Form

Source: https://formity.app/docs/guides/sidebar-navigation

Renders a review of the entered information before launching the workspace. Displays profile, company, and workspace details.

```javascript
<Review
              key={review.id}
              heading="Review & launch"
              message="Everything look right? Launch your workspace."
              content={[
                {
                  text: "Profile",
                  rows: [
                    { label: "Full name", value: format.text(values.name) },
                    { label: "Work email", value: format.text(values.email) },
                    {
                      label: "Job title",
                      value: format.text(values.jobTitle),
                    },
                  ],
                },
                {
                  text: "Company",
                  rows: [
                    {
                      label: "Company name",
                      value: format.text(values.companyName),
                    },
                    {
                      label: "Industry",
                      value: format.industry(values.industry),
                    },
                    {
                      label: "Company size",
                      value: format.companySize(values.companySize),
                    },
                  ],
                },
                {
                  text: "Workspace",
                  rows: [
                    {
                      label: "Workspace name",
                      value: format.text(values.workspaceName),
                    },
                    {
                      label: "Timezone",
                      value: format.timezone(values.timezone),
                    },
                    {
                      label: "Language",
                      value: format.language(values.language),
                    },
                  ],
                },
              ]}
              buttons={{ back: "Back", next: "Launch workspace" }}
              next={next}
              jump={jump}
              prev={workspace.id}
              status={params.status}
            />
```

--------------------------------

### Form Component with Animations

Source: https://formity.app/docs/guides/animating-forms

This component handles form state, navigation, and animations. It uses `AnimatePresence` and `motion.div` for step transitions. Ensure `motion/react` is installed.

```tsx
// components/form/index.tsx
import type { DefaultValues, Resolver } from "react-hook-form";
import type { Back, Next } from "@formity/react";
import type { MotionProps } from "motion/react";

import {
  useMemo,
  useState,
  useEffect,
  useCallback,
  useEffectEvent,
} from "react";

import { useForm, FormProvider } from "react-hook-form";
import { AnimatePresence, motion } from "motion/react";

import type { FormStatus } from "@/types/status";

import { ItemView, type Item } from "./item";
import { Button } from "../button";

interface FormProps<T extends Record<string, unknown>> {
  id: string;
  defaultValues: DefaultValues<T>;
  resolver: Resolver<T>;
  heading: string;
  content: Item[];
  buttons: {
    back: string | null;
    next: string;
  };
  back: Back<T>;
  next: Next<T>;
  status: FormStatus;
  setStatus: (status: FormStatus) => void;
}

export function Form<T extends Record<string, unknown>>({
  id,
  back,
  next,
  status,
  setStatus,
  ...rest
}: FormProps<T>) {
  const [fields, setFields] = useState<T>();

  const move = useEffectEvent((move: FormStatus["move"]) => {
    if (move === "next") return next(fields);
    if (move === "back") return back(fields);
  });

  useEffect(() => move(status.move), [status.move]);

  const handleNext = useCallback<Next<T>>(
    (fields) => {
      setStatus({ type: "form", move: "next", submitting: false });
      setFields(fields);
    },
    [setStatus, setFields],
  );

  const handleBack = useCallback<Back<T>>(
    (fields) => {
      setStatus({ type: "form", move: "back", submitting: false });
      setFields(fields);
    },
    [setStatus, setFields],
  );

  const animate = useMemo(
    () => ({ x: 0, opacity: 1, transition: { delay: 0.25, duration: 0.25 } }),
    [],
  );

  return (
    <AnimatePresence mode="popLayout" initial={false}>
      <motion.div
        key={id}
        inert={Boolean(status.move)}
        animate={animate}
        onAnimationComplete={(definition) => {
          if (definition === animate) {
            setStatus({ type: "form", move: false, submitting: false });
          }
        }}
        {...motionProps(status.move)}
        className="h-full"
      >
        <View
          key={id}
          back={handleBack}
          next={handleNext}
          status={status}
          {...rest}
        />
      </motion.div>
    </AnimatePresence>
  );
}

function motionProps(move: FormStatus["move"]):
 MotionProps {
  if (move === "next") {
    return {
      initial: { x: 50, opacity: 0 },
      exit: { x: -50, opacity: 0, transition: { delay: 0, duration: 0.25 } },
    };
  }
  if (move === "back") {
    return {
      initial: { x: -50, opacity: 0 },
      exit: { x: 50, opacity: 0, transition: { delay: 0, duration: 0.25 } },
    };
  }
  return {};
}

function View<T extends Record<string, unknown>>({
  defaultValues,
  resolver,
  heading,
  content,
  buttons,
  back,
  next,
  status,
}: Omit<FormProps<T>, "id" | "setStatus">) {
  const form = useForm({ defaultValues, resolver });
  return (
    <form
      onSubmit={form.handleSubmit(next)}
      className="flex h-screen w-full items-center justify-center px-4 py-8"
      autoComplete="off"
    >
      <FormProvider {...form}>
        <div className="w-full max-w-md">
          <h2 className="mb-6 text-center text-4xl font-bold text-gray-950">
            {heading}
          </h2>
          <div className="mb-6 flex flex-col gap-4">
            {content.map((field, index) => (
              <ItemView key={index} {...field} />
            ))}
          </div>
          <div className="flex gap-4">
            {buttons.back && (
              <Button
                type="button"
                variant="secondary"
                disabled={status.submitting}
                onClick={() => back(form.getValues())}
              >
                {buttons.back}
              </Button>
            )}
            <Button
              type="submit"
              variant="primary"
              disabled={status.submitting}
            >
              {status.submitting ? "Submitting..." : buttons.next}
            </Button>
          </div>
        </div>
      </FormProvider>
    </form>
  );
}

```

--------------------------------

### Form Element Usage Example

Source: https://formity.app/docs/flow-elements/form

Defines a multi-step form with 'name', 'surname', and 'age' fields. It specifies how to render the form and return the collected data.

```tsx
type Schema = {
  render: React.ReactNode;
  struct: [
    s.Form<{ name: string; surname: string; age: number }>,
    s.Return<{ name: string; surname: string; age: number }>,
  ];
  inputs: Record<never, never>;
  params: Record<never, never>;
};

const flow: Flow<Schema> = [
  {
    form: {
      fields: () => ({
        name: ["", []],
        surname: ["", []],
        age: [20, []],
      }),
      render: ({ fields, next }) => <AboutMeForm fields={fields} next={next} />,
    },
  },
  {
    return: ({ name, surname, age }) => ({ name, surname, age }),
  },
];

```

--------------------------------

### Importing and Using Modules in a Flow

Source: https://formity.app/docs/flow-elements/module

Demonstrates how to import previously defined modules and integrate them into a main flow structure. This allows for composing complex flows from smaller, manageable parts.

```tsx
import * as aboutMe from "./modules/about-me";
import * as condition from "./modules/condition";

type Schema = {
  render: React.ReactNode;
  struct: [s.Module<aboutMe.Schema>, s.Module<condition.Schema>];
  inputs: Record<never, never>;
  params: Record<never, never>;
};

const flow: Flow<Schema> = [
  { module: aboutMe.module },
  { module: condition.module },
];


```

--------------------------------

### Flow Component Setup

Source: https://formity.app/docs/guides/sidebar-navigation

The Flow component is updated to expose form values and the onValuesChange handler through its params. It also exports initialValues for parent state initialization.

```tsx
// flow.tsx
import type { UnionToIntersection } from "type-fest";
import type { s, Flow } from "@formity/react";

import { z } from "zod";

import type { Steps, FormStep, ReviewStep } from "./types/steps";
import type { FormStatus } from "./types/status";

import { Form } from "./components/form";
import { Review } from "./components/review";

import * as constants from "./constants";
import * as format from "./utils/format";

type Values = UnionToIntersection<Fields[keyof Fields]>;

type Fields = {
  profile: {
    name: string;
    email: string;
    jobTitle: string;
  };
  company: {
    companyName: string;
    industry: string;
    companySize: string;
  };
  workspace: {
    workspaceName: string;
    timezone: string;
    language: string;
  };
};

const profile: FormStep<Fields["profile"]> = {
  id: "profile",
  label: "Your profile",
  subtitle: "Name and contact details",
  zod: z.object({
    name: z.string().nonempty("Please enter your full name"),
    email: z.email("Please enter a valid email address"),
    jobTitle: z.string().nonempty("Please enter your job title"),
  }),
};

```

--------------------------------

### Form Submission Logic

Source: https://formity.app/docs/getting-started/tutorial

Defines the flow for form submission, including conditional logic based on user input and the return values for each path. This setup is used with the Formity component.

```typescript
import type { Schema, Status } from "./types";
import type { OnReturn } from "@formity/react";
import { useState, useCallback } from "react";
import { Formity } from "@formity/react";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

import { Form } from "./components/form";
import { Done } from "./components/done";

const flow: Schema = [
  {
    form: {
      fields: () => ({
        name: "",
        surname: "",
        age: 0,
        expertise: "",
      }),
      render: ({ fields, back, next }) => (
        <Form
          key="expertise"
          defaultValues={fields}
          resolver={zodResolver(
            z.object({
              name: z.string().nonempty("Required"),
              surname: z.string().nonempty("Required"),
              age: z.number().positive("Required").min(18, "Must be 18 or older"),
              expertise: z.string().nonempty("Required"),
            }),
          )}
          heading="What is your expertise?"
          content={[
            { type: "text", name: "name", label: "Name" },
            { type: "text", name: "surname", label: "Surname" },
            { type: "number", name: "age", label: "Age" },
            {
              type: "select",
              name: "expertise",
              label: "Expertise",
              placeholder: "Select an option",
              options: [
                { value: "mobile", label: "Mobile development" },
              ],
            },
          ]}
          buttons={{
            back: "Back",
            next: "Submit",
          }}
          back={back}
          next={next}
        />
      ),
    },
  },
  {
    return: ({ name, surname, age, expertise }) => ({
      name,
      surname,
      age,
      softwareDeveloper: true,
      expertise,
    }),
  },

  {
    else: [
      {
        form: {
          fields: () => ({
            interested: ["", []],
          }),
          render: ({ fields, back, next }) => (
            <Form
              key="interested"
              defaultValues={fields}
              resolver={zodResolver(
                z.object({
                  interested: z.string().nonempty("Required"),
                }),
              )}
              heading="Are you interested in learning how to code?"
              content={[
                {
                  type: "select",
                  name: "interested",
                  label: "Interested",
                  placeholder: "Select an option",
                  options: [
                    { value: "yes", label: "Yes, I am interested." },
                    { value: "no", label: "No, it is not for me." },
                    { value: "maybe", label: "Maybe, I am not sure." },
                  ],
                },
              ]}
              buttons={{
                back: "Back",
                next: "Submit",
              }}
              back={back}
              next={next}
            />
          ),
        },
      },
      {
        return: ({ name, surname, age, interested }) => ({
          name,
          surname,
          age,
          softwareDeveloper: false,
          interested,
        }),
      },
    ],
  },
];

export default function App() {
  const [status, setStatus] = useState<Status>({
    type: "form",
    submitting: false,
  });

  const onReturn = useCallback<OnReturn<Schema>>(async (output) => {
    setStatus({ type: "form", submitting: true });

    // Show output in the console
    console.log(output);

    // Simulate a network request
    await new Promise((resolve) => setTimeout(resolve, 2000));

    setStatus({ type: "done" });
  }, []);

  if (status.type === "done") {
    return (
      <Done
        onStartOver={() => setStatus({ type: "form", submitting: false })}
      />
    );
  }

  return <Formity<Schema> flow={flow} onReturn={onReturn} />;
}

```

--------------------------------

### Implement Profile Form Step

Source: https://formity.app/docs/guides/sidebar-navigation

Render the 'profile' form step using the Form component. This includes defining fields, validation, headings, messages, and navigation buttons.

```typescript
export const flow: Flow<Schema> = [
  {
    jump: {
      id: profile.id,
      at: {
        form: {
          fields: (values) => ({
            name: [values.name, []],
            email: [values.email, []],
            jobTitle: [values.jobTitle, []],
          }),
          render: ({ fields, params, next, jump }) => (
            <Form
              key={profile.id}
              defaultValues={fields}
              validate={profile.zod}
              heading="Tell us about yourself"
              message="We'll use this to personalise your experience."
              content={[
                {
                  type: "input",
                  name: "name",
                  label: "Full name",
                  placeholder: "Jane Smith",
                },
                {
                  type: "input",
                  name: "email",
                  label: "Work email",
                  placeholder: "jane@company.com",
                  inputType: "email",
                },
                {
                  type: "input",
                  name: "jobTitle",
                  label: "Job title",
                  placeholder: "Product Manager",
                },
              ]}
              buttons={{ back: null, next: "Continue" }}
              next={next}
              jump={jump}
              prev={null}
              values={params.values}
              onValuesChange={params.onValuesChange}
            />
          ),
        },
      },
    },
  },
```

--------------------------------

### Define Formity Flow Schema

Source: https://formity.app/docs/guides/sidebar-navigation

Define the overall schema for the Formity flow, including the structure of the form, input parameters, and return types. This schema guides the navigation and data handling.

```typescript
export type Schema = {
  render: React.ReactNode;
  struct: [
    s.Jump<s.Form<Fields["profile"]>>,
    s.Jump<s.Form<Fields["company"]>>,
    s.Jump<s.Form<Fields["workspace"]>>,
    s.Jump<s.Form<Record<never, never>>>,
    s.Return<Values>,
  ];
  inputs: Values;
  params: {
    status: FormStatus;
    values: Values;
    onValuesChange: (values: Values) => void;
  };
};
```

--------------------------------

### Define a Formity Flow

Source: https://formity.app/docs/getting-started/introduction

Define a multi-step form as a programmable flow using Formity's core elements. This example demonstrates setting up fields, variables, conditional logic, and return values.

```tsx
const flow: Flow<Schema> = [
  {
    form: {
      fields: () => ({ softwareDeveloper: ["yes", []] }),
      render: ({ fields, next }) => (
        <SoftwareDeveloperForm fields={fields} next={next} />
      ),
    },
  },
  {
    variables: () => ({ language: null }),
  },
  {
    condition: {
      if: ({ softwareDeveloper }) => softwareDeveloper === "yes",
      then: [
        {
          form: {
            fields: () => ({ language: ["", []] }),
            render: ({ fields, back, next }) => (
              <LanguageForm fields={fields} back={back} next={next} />
            ),
          },
        },
      ],
      else: [],
    },
  },
  {
    return: ({ softwareDeveloper, language }) => ({
      softwareDeveloper,
      language,
    }),
  },
];

return <Formity<Schema> flow={flow} onReturn={onReturn} />;

```
Tokens:
Raw