# Multi-Step Form Wizard

### 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.

```erb
<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`:

```sh
rails g stimulus wizard
```

```js
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` :

```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!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lightningrails.com/features-setup/multi-step-form-wizard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.