Forms Steps
Provides a UI to create multi-step form workflows using entity form modes, enabling quick and configurable multistep forms in Drupal.
forms_steps
Install
composer require 'drupal/forms_steps:8.x-1.7'
Overview
Forms Steps is a powerful module that enables site administrators to create multi-step form workflows without writing code. It leverages Drupal's entity form modes to split entity creation/editing across multiple sequential pages.
The module introduces a configuration entity called 'Forms Steps' that defines a complete workflow, including steps (each pointing to an entity type, bundle, and form mode), progress steps for visual progress bar display, and redirection policies for post-completion behavior.
Each workflow instance is tracked via a unique UUID (instance_id), allowing users to navigate between steps while maintaining data consistency. The module automatically creates dynamic routes for each step URL and provides a progress bar block that can be placed anywhere on the page.
Forms Steps also fires events when users transition between steps, allowing developers to implement custom logic such as automated user login after registration or data validation.
Features
- Create multi-step form workflows through an intuitive admin UI without coding
- Support for any fieldable entity type (Node, User, Taxonomy, custom entities)
- Leverage existing Drupal form modes to display different fields on each step
- Dynamic route generation with UUID-based instance tracking for workflow continuity
- Configurable progress bar block with customizable step links and visibility controls
- Customizable button labels (Submit, Cancel, Delete, Previous) per step
- Previous button support for backward navigation within workflows
- Multiple redirection policies after workflow completion (internal path, external URL, route, entity view)
- StepChangeEvent for custom logic during step transitions
- Drush command for importing existing entities into workflow instances
- Workflow instance management with database-backed persistence
- Automatic cleanup of workflow instances when source entities are deleted
- Support for user account creation across multiple steps with security considerations
- Admin theme support for step pages when configured
Use Cases
Multi-step Node Creation
Create a content type with many fields and split them across multiple pages. For example, a job application form could have Step 1 for personal information, Step 2 for work experience, Step 3 for education, and Step 4 for document uploads. Each step shows only relevant fields using form modes.
User Registration Wizard
Split user registration into multiple steps: basic account info, profile details, and preferences. Use the StepChangeEvent to automatically log in the user after the first step, allowing subsequent steps to update their profile. Configure the final step to redirect to the user's profile page.
Order/Checkout Process
Create a multi-step checkout flow for a custom commerce solution. Step 1 collects cart items, Step 2 handles shipping information, Step 3 manages payment details, and Step 4 shows confirmation. The progress bar block helps users track their position in the process.
Survey or Quiz Application
Build complex surveys with multiple pages of questions. Each page (step) can display different fields or question groups. Progress steps show users how far they've progressed through the survey, with optional links to return to previous sections.
Onboarding Workflow
Guide new users through a setup process after registration. Each step collects different information: profile setup, notification preferences, tutorial completion. Use the redirection policy to send users to the dashboard after completing all steps.
Content Import with Existing Data
Use the drush command to import existing content into a workflow. For example, migrate legacy content into a new multi-step editing workflow by attaching existing nodes to specific workflow steps.
Tips
- Create dedicated form modes for each step showing only the relevant fields for that part of the workflow
- Use the Previous button feature to allow users to go back and review/edit earlier steps
- Configure the redirection policy to 'Current Entity' to show users their completed content after the final step
- Place the progress bar block in a prominent location and style it with CSS classes (previous-step, active, next-step)
- For user registration workflows, always have the first step create the user and subsequent steps update the profile
- Use the StepChangeEvent to implement custom validation, notifications, or data manipulation between steps
- Export Forms Steps configurations to sync workflows across environments using Configuration Management
- Enable 'Show links only if concerning steps have been saved' to prevent users from skipping steps via progress bar links
- Test workflows with both new entities and existing entities (via drush command) to ensure proper behavior
Technical Details
Admin Pages 7
/admin/config/workflow/forms_steps
Main administration page listing all configured Forms Steps workflows. From here you can add, edit, delete workflows, and view workflow instances.
/admin/config/workflow/forms_steps/add
Create a new Forms Steps workflow by providing a label, machine name, and optional description.
/admin/config/workflow/forms_steps/edit/{forms_steps}
Configure all aspects of a Forms Steps workflow including steps, progress bar, and redirection settings.
/admin/config/workflow/forms_steps/{forms_steps}/add_step
Add a new step to the Forms Steps workflow by configuring entity type, bundle, form mode, URL, and button settings.
/admin/config/workflow/forms_steps/{forms_steps}/add_progress_step
Add a progress step for the visual progress bar indicating workflow progression.
/admin/config/workflow/forms_steps/workflows/list
View all workflow instances that have been created, showing the workflow tracking data for each multi-step form session.
/admin/config/workflow/forms_steps/settings
Global settings for the Forms Steps module.
Permissions 2
Hooks 6
hook_form_alter
Used internally by Forms Steps to intercept forms on Forms Steps routes and add step navigation handling.
hook_entity_type_alter
Automatically registers form classes for entity form modes used in Forms Steps workflows.
hook_entity_insert
Creates workflow tracking records when entities are created within a Forms Steps workflow.
hook_entity_presave
Updates workflow tracking records when entities are updated within a Forms Steps workflow.
hook_entity_predelete
Automatically deletes workflow instances when the source entity is deleted.
hook_theme
Defines the item_list__forms_steps theme hook for progress bar rendering.
Drush Commands 1
drush forms_steps:attach-entity
Attach an existing entity to a Forms Steps workflow instance. Useful for importing existing content into multi-step workflows or programmatically linking entities to workflows.
Troubleshooting 6
Some entity types (like User) don't have default form classes for custom form modes. Implement hook_entity_type_alter() in a custom module to assign a form class: $entity_types['user']->setFormClass('my_form_mode', 'Drupal\user\ProfileForm');
Ensure the form mode is enabled for the selected bundle at Administration > Structure > [Entity Type] > Manage form display. Clear caches after adding new form modes.
Verify that progress steps are configured for the workflow and that the progress bar block is placed in a visible region via Administration > Structure > Block layout. The block only renders on Forms Steps routes.
For anonymous user registration across multiple steps, either enable automatic login (disable email verification in account settings) or implement a StepChangeEvent subscriber to log in the user after the first step.
This occurs when accessing a step with an invalid instance_id. Ensure users follow the workflow from the first step, or use the drush command to attach existing entities to workflow instances.
Each step must use the same entity type and bundle if editing a single entity across steps. Different entity types/bundles in steps create separate entities. Check step configuration for consistency.
Security Notes 5
- The module respects Drupal's entity access system - users must have create/update permissions for the entity types used in steps
- Anonymous user registration across multiple steps requires careful security consideration - the module cannot grant update permissions to anonymous users for entities they just created
- For user registration workflows, consider using automatic login after the first step or requiring email verification
- Workflow instance IDs are UUIDs passed in URLs - while not easily guessable, they do provide direct access to workflow state
- The 'administer forms_steps' permission grants full control over workflow configurations - assign carefully