Before you begin...

A great user experience can be created with Rails alone. Tools such as Russian Doll caching, UJS, Stimulus, and Turbo Drive are incredibly powerful when combined. Could you build your application using these tools without introducing StimulusReflex?

It might strike you as odd that we would start by questioning whether you need this library at all. Our motivations are an extension of the question we hope more people will ask.

Instead of "Which Single Page App framework should I use?" we believe that StimulusReflex can empower people to wonder "Do we still need React, given what we now know is possible?" 🤯

Video Tutorial: Introduction to StimulusReflex

​Chris from GoRails has released the first of hopefully many tutorial videos demonstrating how to get up and running with StimulusReflex in about ten minutes: ⏱️👍

Hello, Reflex World!

There are two ways to enable StimulusReflex in your projects: use the data-reflex attribute to declare a reflex without any code, or call the stimulate method inside of a Stimulus controller. We can use these techniques interchangeably, and both of them trigger a server-side "Reflex action" in response to users interacting with your UI.

Let's dig into it!

Trigger Reflex actions with data-reflex attributes

This example updates the page with the latest count when the link is clicked:

app/views/pages/index.html.erb
<a href="#"
  data-reflex="click->Counter#increment"
  data-step="1" 
  data-count="<%= @count.to_i %>"
>Increment <%= @count.to_i %></a>

We use data attributes to declaratively tell StimulusReflex to pay special attention to this anchor link. The data-reflex attribute allows us to map an action on the client to code that will be executed on the server.

The syntax follows Stimulus format: [DOM-event]->[ReflexClass]#[action]

The other two attributes data-step and data-count are used to pass data to the server. You can think of them as arguments.

app/reflexes/counter_reflex.rb
class CounterReflex < ApplicationReflex
  def increment
    @count = element.dataset[:count].to_i + element.dataset[:step].to_i
  end
end

StimulusReflex maps your requests to Reflex classes that live in your app/reflexes folder. In this example, the increment action is called and the count is incremented by 1. The @count instance variable is passed to the template when it is re-rendered.

Trigger Reflex actions inside Stimulus controllers

Real-world applications will benefit from additional structure and more granular control. Building on the solid foundation that Stimulus provides, we can import StimulusReflex into our Stimulus controllers and build complex functionality.

Let's build on our increment counter example by adding a Stimulus controller and manually triggering a Reflex action by calling the stimulate method.

1. Declare the appropriate data attributes in HTML.

2. Create a client side StimulusReflex controller with JavaScript.

3. Create a server side Reflex object with Ruby.

4. Create a server side Example controller with Ruby.

We can use the standard Stimulus data-controller and data-action attributes, which can be changed if you have a conflict. There's no StimulusReflex-specific markup required:

app/views/pages/index.html.erb
<a href="#"
  data-controller="counter"
  data-action="click->counter#increment"
>Increment <%= @count %></a>

Now we can create a simple Stimulus controller that extends ApplicationController, which is installed with StimulusReflex. It takes care of making your controller automatically inherit the stimulate method:

app/javascript/controllers/counter_controller.js
import ApplicationController from './application_controller.js'
​
export default class extends ApplicationController {
  increment(event) {
    event.preventDefault()
    this.stimulate('Counter#increment', 1)
  }
}

When the user clicks the anchor, the Stimulus event system calls the increment method on our controller. In this example, we pass two parameters: the first one follows the format [ReflexClass]#[action] and informs the server which Reflex action in which Reflex class we want to trigger. Our second parameter is an optional argument that is passed to the Reflex action as a parameter.

app/reflexes/counter_reflex.rb
class CounterReflex < ApplicationReflex
  def increment(step = 1)
    session[:count] = session[:count].to_i + step
  end
end

Here, you can see how we accept a step argument to our increment Reflex action. We're also now switching to using the Rails session object to persist our values across multiple page load operations. Note that you can only provide parameters to Reflex actions by calling the stimulate method with arguments; there is no equivalent for Reflexes declared with data attributes.

app/controllers/pages_controller.rb
class PagesController < ApplicationController
  def index
    @count = session[:count].to_i
  end
end

Finally, we set the value of the @count instance variable in the controller action. When the page is first loaded, there will be no session[:count] value and @count will be nil, which converts to an integer as 0... our initial value.

StimulusReflex Generator

We provide a generator that performs a scaffold-like functionality for StimulusReflex. It will generate files and classes appropriate to whether you specify a singular or pluralized name for your reflex class. For example, user and users are both valid and useful in different situations.

bundle exec rails generate stimulus_reflex user

This will create but not overwrite the following files:

1. app/javascript/controllers/application_controller.js

2. app/javascript/controllers/user_controller.js

3. app/reflexes/application_reflex.rb

4. app/reflexes/user_reflex.rb

StimulusReflex Cheatsheet

If you're going to be working with StimulusReflex, you might want to bookmark Rafe Rosen's excellent reference for frequently used method names and callbacks: https://devhints.io/stimulus-reflex​