Introducing Stimulus-use composable behaviors for your controllers

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.

Motivations

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.

Stimulus-use

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() {
    useIntersection(this)
    useResize(this)
  }

  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 :

• BetterStimulus
• StimulusReflex
• all of the free screencast on GoRails
• StimulusAwesome

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

stimulus-use / stimulus-use

A collection of composable behaviors for your Stimulus Controllers

A collection of composable behaviors for your Stimulus Controllers

• New lifecycle behaviors: adds new standard behaviors to your Stimulus controllers.
• Composable: compose at will different behaviors in a single controller with mixins.
• Modular: built as ES6 modules, just import what you need and tree shaking will remove the rest.
• Typescript: Types available, better autocompletion.
• Tiny: 3k gzip + tree shaking 🌳🌳🌳

Getting Started

Stimulus 3

If you want to use stimulus-use with Stimulus 3 you can use the version 0.50.0+. This and all future versions are designed to work with the @hotwired/stimulus npm package.

Note: If other packages still depend on the stimulus npm package you can safely keep that in your package.json, this won't break the stimulus-use compability.

Using npm

npm i stimulus-use @hotwired/stimulus

Using yarn

yarn add stimulus-use @hotwired/stimulus

Stimulus 2 and below

If you want to use stimulus-use with Stimulus…

View on GitHub

Comments

[Tac Tacelosky]

This approach (Composable, mixins) makes so much more sense than simply extending re-usable controllers. I wish more stimulus components were written (and documented) this way. Thanks for releasing this very useful collection!