Multi-Step Forms

Step Ordering and Priority

Steps are ordered by priority (higher first). If no priority is defined, steps are ordered by insertion order:

1
2

$builder->addStep('first', FirstType::class, priority: 10);
$builder->addStep('second', SecondType::class);

Skipping Steps

Steps can be conditionally skipped using a callable:

1
2
3
4
5

$builder->addStep(
    'professional',
    ProfessionalType::class,
    skip: fn (User $data) => !$data->isWorker()
);

Skipped steps are not rendered and are ignored during navigation.

Nested Steps

Steps can define child steps, to build a hierarchy matching the composition of your model. Use the createStep() method of the builder to create a step, add its children to it and pass the result to addStep():

1
2
3
4
5
6
7
8
9
10
11
12
13

public function buildFormFlow(FormFlowBuilderInterface $builder, array $options): void
{
    $builder
        ->addStep(
            $builder->createStep('flight', FlightType::class)
                ->addStep('outbound', OutboundFlightType::class)
                ->addStep('return', ReturnFlightType::class)
        )
        ->addStep('passengers', PassengersType::class)
    ;

    $builder->add('navigator', NavigatorFlowType::class);
}

In this example, the flight step contains form fields of its own. When the user clicks the "Next" button, the flow goes through the outbound and return steps before reaching the passengers step.

Child steps are configured like the other ones. Navigation skips the whole branch of a skipped step, which is convenient to make a part of the flow depend on the data submitted in a previous step:

1
2
3
4
5
6
7
8

$builder->addStep(
    $builder->createStep('flight', FlightType::class)
        ->addStep(
            $builder->createStep('return', ReturnFlightType::class)
                ->setSkip(fn (Booking $data) => !$data->isRoundTrip())
                ->addStep('return_seat', SeatType::class)
        )
);

Grouping Steps

When a parent step only exists to give a structural meaning to its children and has no form of its own, create it with the createStepGroup() method:

1
2
3
4
5
6
7
8
9
10
11
12
13

public function buildFormFlow(FormFlowBuilderInterface $builder, array $options): void
{
    $builder
        ->addStep(
            $builder->createStepGroup('flight')
                ->addStep('outbound', OutboundFlightType::class)
                ->addStep('return', ReturnFlightType::class)
        )
        ->addStep('passengers', PassengersType::class)
    ;

    // ...
}

As group steps aren't actual form steps, they are never displayed as the current step: navigation traverses them to the closest child in the direction it moves (the first one when moving forward, the last one when moving backward).

Custom Navigation Buttons

You can define custom navigation buttons independently of the default navigator:

1
2
3
4
5
6
7
8

use Symfony\Component\Form\Flow\Type\NextFlowType;

$builder->add('skip', NextFlowType::class, [
    'clear_submission' => true,
    'validate' => false,
    'validation_groups' => [],
    'include_if' => ['professional'],
]);

Each button type accepts options that control validation behavior, which steps it appears on (include_if), and whether the current submission data is cleared (clear_submission).

Finishing and Resetting the Flow

When the finish button is clicked, the flow is marked as finished, the data storage is cleared (if auto_reset is enabled), and the cursor is reset to the first step. Use $form->isFinished() to check whether the flow has completed.

Rendering Navigation Information

Symfony provides a set of form_flow_*() Twig functions to read the state of the flow inside templates. They are useful to build progress indicators, step lists and navigation menus. All of them take a FormView as their only argument:

• form_flow_current_step(), form_flow_first_step(), form_flow_last_step(), form_flow_next_step() and form_flow_previous_step() return a step name as a string;
• form_flow_steps() returns the list of all step names;
• form_flow_total_steps() returns the number of steps and form_flow_step_index() the zero-based index of the current step;
• form_flow_is_first_step(), form_flow_is_last_step(), form_flow_can_move_back() and form_flow_can_move_next() return a boolean.

The form_flow_next_step() and form_flow_previous_step() methods return null on the last and first steps respectively. When the given form is not part of a flow, all functions return null, except the is_*() and can_*() ones, which return false.

The following example displays the current progress and the list of steps:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<p>
    Step {{ form_flow_step_index(form) + 1 }}
    of {{ form_flow_total_steps(form) }}:
    {{ form_flow_current_step(form) }}
</p>

<ol>
    {% for step in form_flow_steps(form) %}
        <li class="{{ step == form_flow_current_step(form) ? 'active' : '' }}">
            {{ step }}
        </li>
    {% endfor %}
</ol>

{{ form_start(form) }}
    {# this also renders the navigator buttons (previous, next, finish) #}
    {{ form_widget(form) }}
{{ form_end(form) }}

Instead of form_flow_steps(), which returns all the steps defined in the flow, use the visible_steps variable to exclude the steps skipped for the current data:

1
2
3
4
5
6
7

<ol>
    {% for step in form.vars.visible_steps %}
        <li class="{{ step.is_current_step ? 'active' : '' }}">
            {{ step.name }}
        </li>
    {% endfor %}
</ol>

Each step object exposes the following properties:

• name, the name of the step and level, its depth in the flow (0 for the steps defined at the root of the flow);
• index, the zero-based position of the step among its siblings and position, its one-based position among the non-skipped ones (-1 when the step is skipped);
• is_current_step, is_before_current_step, is_after_current_step and has_current_step_descendant, telling where the step stands relative to the current one;
• is_skipped and can_be_skipped;
• is_group, whether the step is a group step;
• children and visible_children, the child steps of the step, the latter excluding the skipped ones.

As visible_steps only contains the steps defined at the root of the flow, use visible_children to render the nested steps too. A group step is never the current step, so rely on has_current_step_descendant to highlight the branch the user is in:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{% macro steps(steps) %}
    <ol>
        {% for step in steps %}
            <li class="{{ step.is_current_step or step.has_current_step_descendant ? 'active' : '' }}">
                {{ step.name }}
                {% if step.visible_children is not empty %}
                    {{ _self.steps(step.visible_children) }}
                {% endif %}
            </li>
        {% endfor %}
    </ol>
{% endmacro %}

{{ _self.steps(form.vars.visible_steps) }}