Multi-Step Forms

Creating and managing multi-step forms with progress indicators, step navigation and conditional step logic.

Overview

The FormStep model lets you break long forms into logical sections with progress tracking. Steps support conditional display, custom icons, per-step validation and flexible navigation. When a form has steps, it automatically renders in multi-step mode.

Core Properties

Property	Type	Description
`title`	string	Step title displayed in progress indicator
`description`	string\|null	Optional step description or instructions
`icon`	string\|null	Icon name for step indicator (optional)
`sort_order`	int	Display order of steps (0-indexed)
`conditions`	array	Conditional logic to show/hide step

Creating Multi-Step Forms

Use the FormBuilder's addStep() method to define steps and assign fields:

app/Http/Controllers/FormController.php

Field Assignment

Fields added after addStep() are automatically assigned to that step. Fields without steps are rendered as single-page forms.

Step Navigation Settings

Control multi-step behavior through form settings:

Setting	Default	Description
`show_progress_bar`	true	Display progress indicator showing current step
`show_step_navigation`	true	Show next/previous buttons between steps
`validate_on_step_change`	true	Validate current step before allowing navigation
`allow_save_draft`	false	Enable saving progress as draft submission
`allow_step_jumping`	false	Allow clicking any step in progress bar (vs. sequential)
`show_step_numbers`	true	Show step numbers (1, 2, 3) in progress indicator

Conditional Steps

Steps can be shown or hidden based on field values from earlier steps:

Step Dependencies

Conditional steps should only reference fields from previous steps. The frontend evaluates conditions in step order.

Relationships

form - BelongsTo Form (parent form)
fields - HasMany FormField (fields in this step)

Frontend Usage

The PolyformMultiStepRenderer component handles the multi-step UI out of the box:

resources/js/Pages/Survey.vue

The usePolyformSteps composable gives you reactive step state and navigation methods.

Programmatic Step Creation

You can also create steps directly via Eloquent:

Step Validation

With validate_on_step_change enabled, only the current step's fields are checked before navigation. On final submission, all steps are validated together.

Draft Submissions

Turn on allow_save_draft to let users save progress and come back later:

Draft submissions have status STARTED
Users can resume from their last completed step
Drafts are scoped to the authenticated user (requires login)
Final submission changes status to SUBMITTED

Progress Persistence

Draft submissions store partial field values, so users can pick up exactly where they left off across browser sessions.

Best Practices

Keep steps to 3-7 fields each for a good user experience
Use clear step titles that tell users what to expect
Enable validation on step change to catch errors early
Group related fields together (e.g., Contact Info, Preferences, Review)
Think about mobile users when planning the step flow
Show a progress bar for forms with more than 3 steps

Fields Submissions