Multi Step Form Component

The Multi Step Form component provides a powerful foundation for building complex, multi-step forms with built-in validation, data persistence, and smooth animations. Perfect for surveys, wizards, and complex data collection workflows.

Key Features

Step Management: Flexible step configuration with back/forward navigation
Data Persistence: Optional auto-save functionality with customizable storage and form flow history
Validation: Built-in Zod schema validation with custom validation support
Dynamic Step Management: Customize form flow through the schema, conditional steps made easy

Configuration Overview

The Multi Step Form requires configuration across several files to work properly:

1. Form Schema Definition

First, define your form’s schema and steps in a dedicated file (e.g., src/schemas/form-flows/your-form.ts)

1
import { z } from 'zod';
2

3
export const flatSchema = z.object({
4
  field1: z.string().min(2),
5
  field2: z.string().email(),
6
  field3: z.string(),
7
});

The schema here will be used to validate the form data in the Astro action and local storage.

2. Form Steps Definition

Use the defineFormSchema function to define your form’s steps. The function accepts an object where the keys are the step IDs and the values are the step configurations. The file should be in src/lib/client/form-flows/your-form.ts

CAUTION

Do not put the form steps in the same file as the schema. Astro actions depend on the schema, and the form steps definition will likely be using custom components that are not available on the server because they extend HTMLElement. Read Astro Actions Undefined for more information.

Each step configuration is defined using the defineStep function. This function accepts a configuration object that describes the step’s schema, validation, and other options.

DefineStep arguments

Required Props

defineStep Arguments
Prop	Type	Description
schema	ZodSchema	The Zod schema for the step's fields
onComplete	(formData: FormData) => Promise<string \| undefined>	Handler called when step is complete, returns next step ID
showSubmitButton	boolean	Show submit button instead of next
changeOnSelect	boolean	Advance to next step on selection
selectHandler	(form: HTMLElement) => selectHandlerResult \| null	Custom changeOnSelect behavior handler
processInput	Record<string, (value: string) => Promise<unknown> \| unknown>	Pre-process field values before validation
validate	Record<string, (formData: FormData) => Promise<{ success: boolean, errors?: string[] }>>	Custom validation functions
onReturn	(form: HTMLFormElement) => Promise<void>	Handler called when returning to step
onEnter	(form: HTMLFormElement) => Promise<void>	Handler called when entering step

1
import { defineFormSchema, defineStep } from '@/schemas/multistep';
2
import { flatSchema } from './basic-schema';
3

4
export const yourFormSteps = defineFormSchema({
5
  stepOne: defineStep({
6
    schema: flatSchema.pick({
7
      field1: true,
8
      field2: true,
9
    }),
10
    async onComplete(formData) {
11
      if (formData.get('field1') === 'helloworld') {
12
        return 'secretStep'; // Return next step ID
13
      }
14
      return 'stepOne'; // Return same step ID
15
    },
16
  }),
17
  stepTwo: defineStep({
18
    schema: flatSchema.pick({
19
      field3: true,
20
    }),
21
    showSubmitButton: true,
22
    async onComplete() {
23
      return undefined; // Form complete
24
    },
25
  }),
26
  secretStep: defineStep({
27
    schema: flatSchema.pick({
28
      field3: true,
29
    }),
30
    showSubmitButton: true,
31
    async onComplete() {
32
      return undefined; // Form complete
33
    },
34
  }),
35
});

selectHandler

The selectHandler option is used to handle the selection for the step when using the changeOnSelect option. It should return an object with the following properties:

Required Props

selectHandler
Prop	Type	Description
getData	() => FormData	A function that is called to get the data for the step. It should return a `FormData` object.
subscribe	(callback: (value?: string) => void) => void	A function that is called to setup any event listeners to the data for the step. It's argument is a callback function that is called when the data changes via the event listener.
cleanup	() => void	A function that is called to cleanup the event listeners for the step.

1
import { defineFormSchema, defineStep } from '@/schemas/multistep';
2
import { flatSchema } from './basic-schema';
3

4
export const yourFormSteps = defineFormSchema({
5
  stepOne: defineStep({
6
    schema: flatSchema.pick({
7
      field1: true,
8
      field2: true,
9
    }),
10
    async onComplete(formData) {
11
      if (formData.get('field1') === 'helloworld') {
12
        return 'secretStep'; // Return next step ID
13
      }
14
      return 'stepOne'; // Return same step ID
15
    },
16
  }),
17
  stepTwo: defineStep({
18
    schema: flatSchema.pick({
19
      field3: true,
20
    }),
21
    showSubmitButton: true,
22
    async onComplete() {
23
      return undefined; // Form complete
24
    },
25
  }),
26
  secretStep: defineStep({
27
    schema: flatSchema.pick({
28
      field3: true,
29
    }),
30
    showSubmitButton: true,
31
    async onComplete() {
32
      return undefined; // Form complete
33
    },
34
  }),
35
});

3. Local Storage Schema

Add your form’s schema to schemas/local-data.ts to enable data persistence:

1
import { z } from 'zod';
2
import { flatSchema } from './basic-schema';
3

4
export const ZLocalDataSchemas = z.object({
5
  // ... existing schemas ...
6
  ['your-form']: flatSchema,
7
});

4. Form HTML

Create your form page component (e.g., pages/your-form.astro) and use the MultistepForm component for each step.

1
---
2
import MSForm from '@/components/NST-components/UI/multistep-form/MultistepForm.astro';
3
import MSFormSection from '@/components/NST-components/UI/multistep-form/FormSection.astro';
4
import Input from '@/components/NST-components/UI/input/Input.astro';
5
---
6

7
<MSForm
8
  name="your-form"
9
  animation={{ type: 'slide', direction: 'horizontal' }}
10
  scrollToTop
11
>
12
  <MSFormSection name="stepOne">
13
    <Input type="text" name="field1" required />
14
    <Input type="email" name="field2" required />
15
  </MSFormSection>
16

17
  <MSFormSection name="secretStep">
18
    <Input type="text" name="field3" required />
19
  </MSFormSection>
20

21
  <MSFormSection name="stepTwo">
22
    <Input type="text" name="field3" required />
23
  </MSFormSection>
24
</MSForm>

5. Form Script

Create your form page script (e.g., scripts/your-form.ts):

1
<script>
2
  //eslint-disable-next-line
3
  // @ts-nocheck
4
  import { yourFormSteps } from './basic-steps';
5
  import { ready } from '@/components/NST-components/base';
6
  import { genericSaveDataHandler } from '@/lib/client/storage';
7
  import { ActionError } from 'astro:actions';
8

9
  async function init() {
10
    const form = await ready(
11
      document.querySelector('multistep-form')
12
    );
13

14
    if (!form) return;
15

16
    form.setStepConfig({
17
      config: yourFormSteps,
18
      firstStep: 'stepOne',
19
      localDataKey: 'your-form',
20
    });
21

22
    form.submitHandler = async (formData) => {
23
      try {
24
        await submitFormData(formData);
25
        return undefined;
26
      } catch {
27
        return new ActionError({
28
          message: 'Submission failed',
29
          code: 'SUBMIT_ERROR',
30
        });
31
      }
32
    };
33

34
    // Optional: Enable auto-save
35
    form.saveDataHandler = genericSaveDataHandler('your-form');
36
  }
37

38
  init();
39
</script>

Auto-save Functionality

Implement auto-save functionality with debouncing. You can set the debounce rate in milliseconds, and define the function that runs on form auto-save. There’s three ways to set this up.

1
import { ready } from '@/components/NST-components/base';
2
import type { MSFElement } from '@/components/NST-components/UI/multistep-form/data';
3
import { getData, setData } from '@/lib/client/storage';
4

5
const contactForm = await ready(
6
  document.querySelector<MSFElement>('multistep-form[name="contact-form"]')
7
);
8

9
if (contactForm) {
10
  contactForm.saveDataHandler = (data) => {
11
    const contactFormData = {
12
      name: data.get('name')?.toString(),
13
      email: data.get('email')?.toString(),
14
      message: data.get('message')?.toString(),
15
    };
16

17
    setData('contact-form', {
18
      ...getData('contact-form'),
19
      ...contactFormData,
20
    });
21
  };
22
  //If youre not saving all the data, you can disable the step history so the user will start on the first step if the page refreshes. But the data will still be saved.
23
  contactForm.saveStepHistory = false;
24
}

1
import { ready } from '@/components/NST-components/base';
2
import type { MSFElement } from '@/components/NST-components/UI/multistep-form/data';
3

4
const localDataKey = 'contact-form';
5

6
const contactForm = await ready(
7
  document.querySelector<MSFElement>('multistep-form[name="contact-form"]')
8
);
9

10
if (contactForm) {
11
  //Can also be set in the forms component props without needing a script
12
  contactForm.localDataKey = localDataKey;
13
}

1
import { ready } from '@/components/NST-components/base';
2
import type { MSFElement } from '@/components/NST-components/UI/multistep-form/data';
3
import { genericSaveDataHandler } from '@/lib/client/storage';
4

5
const localDataKey = 'contact-form';
6

7
const contactForm = await ready(
8
  document.querySelector<MSFElement>('multistep-form[name="contact-form"]')
9
);
10

11
if (contactForm) {
12
  contactForm.saveDataHandler = genericSaveDataHandler(localDataKey, {
13
    dontSave: ['add_to_newsletter'],
14
  });
15
  contactForm.saveStepHistory = false;
16
}

DANGER

genericSaveDataHandler and localDataKey will save all form data to local storage. For forms that have sensitive data, either create a custom saveDataHandler, or use the dontSave option in genericSaveDataHandler to exclude sensitive data.

Form Functions API

The Form component provides the following functions:

MultistepForm Functions
Name	Type	Description
get: data	() => FormData	A function that is called to get the data for the form.
set: stepConfig	() => void	A function that is called to setup the step config for the form.
set: saveDataHandler	(data: { data: Record<string, string \| File>; stepHistory: string[]; currentStep: string; }) => void	A function that is called to setup the save data handler for the form.
set: submitHandler	(formData: FormData) => Promise<ActionError \| undefined>	A function that is called to submit the form.

Advanced Features

Data Persistence

Enable auto-save and form flow history functionality:

1
form.saveDataHandler = (data) => {
2
  localStorage.setItem('form-data', JSON.stringify(data));
3
};

Custom Validation

Add custom validation to any step:

1
defineStep({
2
  schema: z.object({
3
    username: z.string(),
4
  }),
5
  validate: {
6
    username: async (formData) => {
7
      const username = formData.get('username');
8
      const isAvailable = await checkUsernameAvailability(username);
9
      return {
10
        success: isAvailable,
11
        errors: isAvailable ? undefined : ['Username already taken'],
12
      };
13
    },
14
  },
15
});

Select Handlers

Create interactive selection steps:

1
defineStep({
2
  schema: z.object({
3
    plan: z.enum(['basic', 'pro', 'enterprise'])
4
  }),
5
  changeOnSelect: true, // Advance on selection
6
  selectHandler: (form) => ({
7
    subscribe: (callback) => {
8
      form.addEventListener('click', (e) => {
9
        const plan = e.target.closest('[data-plan]')?.dataset.plan;
10
        if (plan) callback(plan);
11
      });
12
    },
13
    cleanup: () => {
14
      // Cleanup event listeners
15
    }
16
  })

MultistepForm Props API

Required Props

MultistepForm Extends <div> HTMLElement
Prop	Type	Default	Description
name	string	-	Unique identifier for the form
animation	{ type: "fade" \| "slide", direction: "horizontal" \| "vertical", duration: number }	{ type: "fade", direction: "horizontal", duration: 300 }	Animation configuration
scrollToTop	boolean	false	Scroll to top on step change
submitButtonText	string	Submit	Submit button text
submitButtonTextSubmitting	string	Submitting...	Text during submission
submitButtonProps	ComponentProps<typeof Button>	{}	Submit button props
backButtonProps	ComponentProps<typeof Button>	{}	Back button props
nextButtonProps	ComponentProps<typeof Button>	{}	Next button props

FormSection Element

The FormSection element is used to wrap the form fields for each step. It extends the <form> element and is used to wrap the form fields for each step.

FormSection Props API

Required Props

FormSection Extends <form> HTMLElement
Prop	Type	Default	Description
name	string	-	Unique identifier for the form

Limited Time Launch Sale

Get started with our Multi Step Form component and other powerful UI components in our AstroJS starter template!

GET 60% OFF!

Form Standard

Directory

Directory

Multi Step Form Component

Key Features

Configuration Overview

1. Form Schema Definition

2. Form Steps Definition

DefineStep arguments

selectHandler

3. Local Storage Schema

4. Form HTML

5. Form Script

Auto-save Functionality

Form Functions API

Advanced Features

Data Persistence

Custom Validation

Select Handlers

MultistepForm Props API

FormSection Element

FormSection Props API

On This Page