DEV Community

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

Posted on

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
  }
}
Enter fullscreen mode Exit fullscreen mode

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
  }
}
Enter fullscreen mode Exit fullscreen mode

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 Sauce test status


Stimulus Use Example


  • 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

npm

npm i stimulus-use
Enter fullscreen mode Exit fullscreen mode

yarn

yarn add stimulus-use
Enter fullscreen mode Exit fullscreen mode

Documentation

We got you covered 👉 stimulus-use.github.io/stimulus-use

Mixins

Observers

This set of mixins is built around the Observer APIs and custom events to enhance your controllers with new behaviors.

Mixin Description NEW Callbacks
useClickOutside Tracks the clicks outside of the element and adds a new lifecycle callback clickOutside. clickOutside
useHotkeys Registers hotkeys using the hotkeys-js library and binds them to handler methods
useHover Tracks the user's mouse movements over an element

Discussion (0)