DEV Community

Cover image for Introducing Stimulus-use composable behaviors for your controllers

Introducing Stimulus-use composable behaviors for your controllers

adrienpoly profile image Adrien Poly ・3 min read

TL;DR : it is not React hooks for Stimulus, just a simple way to add new behaviors and lifecycle methods to your controllers.

From the early days of Stimulus, I enjoyed the simplicity and elegance of this modest framework. Nice conventions, simple and flexible API and not the least very robust.


In the past I explored several ways to create standard controllers either wrappers of libraries stimulus-flatpickr or stimulus-conductor. While the first got a bit of traction mostly due to the popularity of Flatpickr, very few standard Stimulus controllers really stand out from the crowd.

I spent some time recently doing quite a bit of React and got to discover the hooks and among them the react-use library.

While in no way I ambition to bring full-blown hooks to Stimulus, I think there is a sweet spot for having composable modules that can enhance with new behaviors your controllers.


So with this in mind, I imagined Stimulus-use. For now, it is a modest set of new behaviors (your can think of lifecycle events too) that you can add to your controller. For this initial release, it adds only a few behaviors but the objective was to get it out, show it, get it tested and get feedbacks on the overall API.

Extend or Compose

All new behavior are available either as a Controller that you can extend.

import { IntersectionController } from 'stimulus-use'

export default class extends IntersectionController {
  appear(entry) {
    // triggered when the element appears within the viewport

Or as useFunction you can use when you want to enhance your controller with a new behavior or compose several new ones into a single Controller.

import { Controller } from 'stimulus'
import { useIntersection, useResize } from 'stimulus-use'

export default class extends Controller {
  connect() {

  appear(entry) {
    // triggered when the element appears within the viewport

  resized({ height, width }) {
    // trigered when the element is resized

Future & vision

While I don't think all behaviors available in React-use would make sens in Stimulus, quite a few are interesting and can be ported in a Stimulus way to this project. Things like idle, visible, windowResize, clipboard, lazyImage, localStorage, animations, clipboard etc.

While things tends to move slowly within Stimulus core (and I don't think it is a real issue as long as the list of issues remains close to nil) and as more and more people are getting into Stimulus we see definitely a need for more examples and standard patterns.
Some great projects such as :

are really helping

I hope this project can bring together more contributors so that we can all create in a more agile way some enhancement to Stimulus that would be :

  • Standard, (stop reinventing the wheel)
  • Battle tested
  • Polyfilled
  • Documented
  • easy to use and compose with existing code

All contributions/contributors are welcome just ping me here or on the issues/PR Stimulus-use

GitHub logo stimulus-use / stimulus-use

A collection of composable behaviors for your Stimulus Controllers

A collection of composable behaviors for your Stimulus Controllers

npm version minified + gzip size types included types included

  • New lifecycle behaviors: adds new standard behaviors to your Stimulus controllers.
  • Composable: compose at will different behaviors in a single controller.
  • Modular: built as ES6 modules, just import what you need and tree shaking will remove the rest.
  • Typscript: Types available, better autocompletion.
  • Tiny: 1k gzip
  • MIT Licensed: free for personal and commercial use.

Getting Started


npm i stimulus-use


yarn add stimulus-use

Modules and Controllers

  • Observers

    Sets of controllers arround the Observer APIs

    useFunction/Controller Description NEW Callbacks
    Tracks the element's intersection and adds appear, disappear callbacks to your controller. appear
    Tracks the element's size and adds a new lifecyle callback resized. resized
  • Application

Extend or compose

Stimulus-use can be used in two manners: extending or composing



Discussion (0)

Editor guide