🧙‍♂️Multi-Step Form Wizard

Break long forms into manageable steps

Overview

The multi-step form wizard allows you to break long forms into manageable steps, improving the user experience by only displaying one step at a time. It's powered by a lightweight Stimulus.js controller and integrates seamlessly with simple_form and Tailwind CSS in Lightning Rails.

Installation & Setup

Follow these steps to implement a form wizard in your Lightning Rails project.

1. Create the Form View

Wrap your form in a <div data-controller="wizard"> and split it into multiple steps using data-wizard-target="step" on each section.

<div data-controller="wizard" class="space-y-6">
  <%= form_with model: @model, local: true, html: { class: "space-y-4" } do |f| %>
    <!-- Step 1 -->
    <div data-wizard-target="step" class="card bg-base-100 shadow p-6">
      <div class="form-control">
        <%= f.label :first_name, class: "label" %>
        <%= f.text_field :first_name, class: "input input-bordered" %>
      </div>

      <div class="mt-4 flex justify-end">
        <%= button_tag "Next", type: "button",
          data: {
            action: "click->wizard#goToNext",
            next_step: "1"
          },
          class: "btn btn-primary" %>
      </div>
    </div>

    <!-- Step 2 -->
    <div data-wizard-target="step" class="card bg-base-100 shadow p-6 hidden">
      <div class="form-control">
        <%= f.label :last_name, class: "label" %>
        <%= f.text_field :last_name, class: "input input-bordered" %>
      </div>

      <div class="mt-4 flex justify-between">
        <%= button_tag "Previous", type: "button",
          data: {
            action: "click->wizard#goToPrevious",
            previous_step: "1"
          },
          class: "btn btn-outline" %>

        <%= button_tag "Next", type: "button",
          data: {
            action: "click->wizard#goToNext",
            next_step: "2"
          },
          class: "btn btn-primary" %>
      </div>
    </div>

    <!-- Step 3 -->
    <div data-wizard-target="step" class="card bg-base-100 shadow p-6 hidden">
      <div class="form-control">
        <%= f.label :email, class: "label" %>
        <%= f.email_field :email, class: "input input-bordered" %>
      </div>

      <div class="mt-4 flex justify-between">
        <%= button_tag "Previous", type: "button",
          data: {
            action: "click->wizard#goToPrevious",
            previous_step: "2"
          },
          class: "btn btn-outline" %>

        <%= f.submit "Submit", class: "btn btn-success" %>
      </div>
    </div>
  <% end %>
</div>

2. Create the Stimulus Controller

Add this Stimulus controller in app/javascript/controllers/wizard_controller.js:

rails g stimulus wizard

import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  static targets = ['step']

  goToNext(event) {
    const nextStep = event.target.dataset.nextStep - 1
    const actualStep = event.target.dataset.nextStep

    this.stepTargets[nextStep].classList.add("hidden")
    this.stepTargets[actualStep].classList.remove("hidden")
  }

  goToPrevious(event) {
    const previousStep = event.target.dataset.previousStep - 1
    const actualStep = event.target.dataset.previousStep

    this.stepTargets[actualStep].classList.add("hidden")
    this.stepTargets[previousStep].classList.remove("hidden")
  }
}

Make sure the controllers are registered in application.js :

// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
import "@hotwired/turbo-rails"
import "controllers"

Usage

• Each step is wrapped in a div with data-wizard-target="step".

• Use class="hidden" (Tailwind utility) to hide inactive steps.

• Navigation is handled via button_tag with data-action for Stimulus event bindings.

• next_step and previous_step indicate the index of the step to show/hide.

Best Practices

• Keep each step concise and focused.

• Validate inputs before allowing the user to proceed (add validations or checks in the controller if needed).

• Use consistent styling with Tailwind to provide visual cues for step transitions.

Troubleshooting

Issue: Nothing happens when clicking "Next" or "Previous". Solution:

• Ensure the Stimulus controller is properly registered and compiled.

• Verify that data-controller="wizard" and data-wizard-target="step" are correctly placed.

• Make sure the buttons have the correct data-action, next_step, or previous_step.

Issue: Steps aren't hiding/showing properly. Solution:

• Confirm that class="hidden" is being toggled correctly.

• Check that stepTargets correspond to the order of steps in your HTML.

---

Let me know on Slack if you'd like an enhanced version with progress indicators or form validation!