Multi Step Forms in Rails
  • Notes

  • Using a gem for this adds additional complexity and maintenance burden which is unnecessary given that the "state machine" component of multi step forms is actually very straight forward. So please do not use multi step wizard gems like Wizard.

  • Requirements

    • Easy to understand

    • Uses the server for state

    • Allows partial completion (user can leave & come back)

  • Steps

  • First, we're going to create a new ActiveRecord model that will track the user journey from beginning to end. For example, for a fintech product the model might be called KycOnboarding. Then, we expose a new method called validation_set using Rails' attr_accessor. What this means is that we can pass information around on the KycOnboarding model without persisting it to the database. You'll see why that's useful later on.

  • Additionally, in order to allow a user to leave their application and come back, we need to generate a "shortcode" that we can use to identify it.

  • class KycOnboarding < ApplicationRecord
      attr_accessor :validation_set  
      before_validation :generate_shortcode
      def generate_shortcode
        if self.shortcode.blank?
          loop do
            self.shortcode = SecureRandom.alphanumeric(5).downcase
            break string unless KycOnboarding.where(shortcode: string).first
  • Forms & Conditional Validations

  • A multi step form can have dozens of inputs, all which need to be validated. We can use Active Record validations for this as we usually would in Rails. The only difference is that we want to run different validations at different steps. For example on the first step we want to validate the name, then on step 2 we validate the email, then the phone number, and so on.

  • Firstly, we're going to handle every step of the form of with a single controller action. If the user is trying to access an existing application, we fetch that. Otherwise we create a new one.

  • class KycOnboardingsController < ApplicationController
      def new
      def get_kyc_onboarding
        if params[:shortcode].present?
          @kyc_onboarding = KycOnboarding.find_by_shortcode(params[:shortcode])
          @kyc_onboarding =
  • On to the views - because we're using one controller action for all steps, even if our wizard has 30 steps, they'll all get wrapped & submitted inside a single form.

  • <!-- /app/views/onboarding/form.html.erb  -->
    <% @current_step = @kyc_onboarding.current_step %>
    <form method="post" action="<%= new_kyc_onboarding_path %>" >
      <%= render partial: "/onboarding/#{@current_step}_step" %>
      <input type="submit" />
  • Validations based on the step the user is on

  • We mentioned earlier that we need to have a way to tell Rails to run different validations at different steps. On the model, we've already added the validation_set accessor, which means we can now pass that through from the view, to the controller, and into the model.

  • On the view, we're going to use a hidden input field in the form, to tell the controller which set of validations to run.

  • <!-- /app/views/onboarding/_phone_step.html.erb  -->
    <input type="hidden" name="kyc_onboarding[validation_set]" value="phone" >
    <input type="text" name="kyc_onboarding[phone]" />
  • In the controller

  • class KycOnboardingsController < ApplicationController
      def new 

      def new_kyc_onboarding_params
  • Now, because we're passing validation_set through from the view and assigning it in the controller, we can use it for conditional validations on the model, which looks like this.

  • class KycOnboarding < ApplicationRecord
      validates_presence_of :name, if: proc { |kyc| kyc.validation_set == "name"  }
      validates_presence_of :phone, if: proc { |kyc| kyc.validation_set == "phone"  }
      validates_presence_of :name, if: proc { |kyc| kyc.validation_set == "email"  }

  • Website Page