Advanced Stimulus: Custom Action Options

Stimulus allows you to register your own custom action options. These are the things you can append to an action, like keypress->input#validate:prevent (as shown in the article on Stimulus Features You (Didn’t) Know). :prevent is an action option and will prevent the default event (similar to adding event.preventDefault()). Other available options are: :stop, and :self.

You can create your own as well! Allowing you to squeeze even more out of Stimulus (who would’ve thought a modest framework had so many feature?!).

I want to list a few suggestions to help you get an idea of what they can do and inspire you to make your own.

The basics

You can create your own action options with the Application.registerActionOption method. The method would then either return true or false, based on the logic you added.

The basics look like this:

// app/javascript/controllers/application.js
import { Application } from "@hotwired/stimulus"

const application = Application.start()

application.registerActionOption("fire", ({ event, value }) => {
  // any logic that returns true/false
}

When it returns true, the action it is appended to, would run. Used like this: click->controller#action:fire.

With the basics done, let’s look at some examples on how you could use it.

WhenOutside

A common action is to click outside of an element to hide it, for example with modals or dropdowns. Logic would be something like this:

application.registerActionOption("whenOutside", ({ event, element }) => {
  return !element.contains(event.target);
});

And your Stimulus controller could look like this:

// app/javascript/controllers/dropdown_controller.js
import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static targets = ["menu"];

  show() {
    this.menuTarget.removeAttribute("hidden");
  }

  hide() {
    this.menuTarget.setAttribute("hidden", true);
  }
}

Then in your HTML:

<div data-controller="dropdown">
  <button data-action="dropdown#show:stop">Show</button>

  <ul data-dropdown-target="menu" data-action="click@window->dropdown#hide:whenOutside">
  </ul>
</div>

Only when you click outside the ul with data-dropdown-target="menu" will it hide the target. Did you notice the :stop action option? I’ve explored it too in the article on Stimulus Features You (Didn’t) Know.

Throttled

Now assume your dropdown_controller.js has a toggle method and you only want your users to toggle it every 1000ms for whatever reason (no judgement!).

const throttles = new WeakMap();

application.registerActionOption("throttled", ({ element }, { wait = 1000 } = {}) => {
  if (!throttless.has(element)) {
    throttles.set(element, 0);
  }

  const now = Date.now();
  const lastRun = throttles.get(element);

  if (now - lastRun >= wait) {
    throttles.set(element, now);

    return true;
  }

  return false;
});

This will only return true once every 1000ms.

🚨 WeakMap? WTF?! I am working on a book so it’s less scary! Pre-order JavaScript for Rails Developers.

Let’s extend the dropdown_controller.js with a toggle method:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["menu"];

  show() {
    this.menuTarget.removeAttribute("hidden");
  }

  toggle() {
    this.menuTarget.toggleAttribute("hidden");
  }

  hide() {
    this.menuTarget.setAttribute("hidden", true);
  }
}

Use it like this:

<div data-controller="dropdown">
  <button data-action="dropdown#toggle:stop:throttled">Show & Hide</button>

  <ul data-dropdown-target="menu" data-action="click@window->dropdown#hide:whenOutside">
  </ul>
</div>

See how it’s possible to stack action options? Both stop and throttled are used.

WithMetakey

Another example could be when you only want to open the dropdown when the meta () or ctrl key is pressed

application.registerActionOption("withMetaKey", ({ event }) => {
  return event.metaKey;
});

Use it in your HTML like so:

<div data-controller="dropdown">
  <button data-action="dropdown#toggle:stop:throttled:withMetaKey">Show & Hide</button>

  <ul hidden data-clicker-target="menu" data-action="click@window->dropdown#hide:whenOutside">
    <li>Menu Item</li>
  </ul>
</div>

The dropdown will only be shown whenever *cmd is pressed too when clicking.

One more? One more!

WithConfirm

Want to show a confirm dialog before you show the dropdown?

application.registerActionOption("withConfirm", ({ element }) => {
  return confirm(element.dataset.confirm || "Are you sure?");
});

And in your HTML:

<div data-controller="dropdown">
  <button data-action="dropdown#toggle:stop:throttled:withMetaKey:withConfirm">Show</button>

  <ul hidden data-clicker-target="menu" data-action="click@window->dropdown#hide:whenOutside">
    <li>Menu Item</li>
  </ul>
</div>

And all these stacked custom actions will work! For the given example not practical, but it shows all the things you can do.

As you noticed, I like to name the custom action options so they make it easy to understand when read in the action:

• click@window->dropdown#hide:whenOutside;
• dropdown#show:withConfirm.

Personal preference. You can of course name them however you want.

For lots of these examples you would normally need to create separate actions (eg. hideWithKey), but not with custom action options. Once you’ve seen them in use, you will find plenty of use cases for them.

Let me know if you already have created an custom action option that I should list here to inspire (and copy!) others.

❗Btw I built a small package to group the best custom action options together, called stimulus-fx. 👀