stimulus-use

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.
• Modular: built as ES6 modules, just import what you need and tree shaking will remove the rest.
• Typescript: Types available, better autocompletion.
• Tiny: 1k gzip
• MIT Licensed: free for personal and commercial use.

Getting Started

npm

npm i stimulus-use

yarn

yarn add stimulus-use

Modules and Controllers

• Observers

  This set of controllers is built around the Observer APIs

  useFunction/Controller	Description	NEW Callbacks
  useIntersection IntersectionController	Tracks the element's intersection and adds appear, disappear callbacks to your controller.	appear disappear
  useResize ResizeController	Tracks the element's size and adds a new lifecyle callback resize.	resize
  useClickOutside ClickOutsideController	Tracks the clicks outside of the element and adds a new lifecyle callback clickOutside.	clickOutside

• Application

  • useApplication, ApplicationController — supercharged controller for your application.

• Idle

  • useIdle, IdleController — Tracks if the user is idle on your page and adds away and back callbacks to your controller.

Extend or compose

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

Extending

You can create your Stimulus controller from a pre-built Stimulus-use controller which offers the new behavior you're looking for. This method works perfectly when you only need a single behavior for your controller.

import { IntersectionController } from 'stimulus-use'

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

Composing

When you need multiple behaviors or you are already extending your controller from another one, you can easily add new behavior with the built-in use functions.

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
  }

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

Launch a local playground

Play with Stimulus-use controllers locally before adding them to one of your projects.

Fork and clone the repo (SSH):

git clone [e-mail]:stimulus-use/stimulus-use.git

Once in your local stimulus-use directory, run:

yarn install

Then, build the library locally

yarn build

Launch the playground locally (available at http://localhost:8080/ by default):

yarn start

Contributors ✨

Made with :heart: by @adrienpoly and all these wonderful contributors (emoji key):

Marco Roth 🚇 💻	Philipp Daun 🐛	M. E. Patterson 🐛	Jonathan Sundqvist 📖	Rui Freitas 📖	Nicolas Filzi 📖	Benjamin Darcet 📖
juancarlosasensio 📖	lidqqq 🚇 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Acknowledgments

Continuous integration and cross browser testing is generously provided Sauce Labs.