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

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 lifecyle callback clickOutside.	clickOutside
useIdle	Tracks if the user is idle on your page and adds away and back callbacks to your controller.	away back
useIntersection	Tracks the element's intersection and adds appear, disappear callbacks to your controller.	appear disappear
useVisibility	Tracks the page visibility and adds visible, invisible callbacks to your controller.	visible invisible
useResize	Tracks the element's size and adds a new lifecyle callback resize.	resize
useWindowResize	Tracks the size of the window object and adds a new lifecyle callback windowResize.	windowResize

Optimization

A set of mixin to optimize performances.

Mixin	Description
useDebounce	Adds the ability to specify an array "debounces" of functions to debounce.
useMemo	Memoize expensive getters by mixing in useMemo and adding a static memos array.
useThrottle	Adds the ability to specify an array "throttles" of functions to throttle.

Application

| Mixin| Description | |useApplication, ApplicationController| supercharged controller for your application.| |useDispatch|Adds a dispatch helper function to emit custom events. Useful to communicate between different controllers.|

Extend or compose

Stimulus-use can be used in two ways: composing with mixins or extending built-in controllers

Composing with mixins

This is the prefered approach as it bring the most flexibility. Simply import a mixin and apply it in the connect or initialize to adds new behaviors to you controller. You can combine several mixins within the same 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
  }

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

Extending built-in controllers

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
  }
}

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 🚇 🐛	Julian Rubisch 💻 👀	Takuya Fukuju 📖

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

Acknowledgments

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