stimulus-use: A JavaScript repository from valentinorusconi

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 has several breaking changes. If you want to use Stimulus-Use with Stimulus 3 you can use the current beta version of Stimulus-Use yarn add stimulus-use@beta. All contribution to Stimulus 3 features are now on the stimulus-3 branch

npm

npm i stimulus-use

yarn

yarn add stimulus-use

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 and adds mouseEnter and mouseLeave callbacks to your controller.	`mouseEnter` `mouseLeave`
`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`
`useMatchMedia`	Tracks if the window matches a media query string.	`is[Name]`, `not[Name]` and `[name]Changed`
`useMutation`	Tracks mutations on an element, its attributes and/or subtree. Adds a mutate callback to your controller.	`mutate`
`useResize`	Tracks the element's size and adds a new lifecycle callback resize.	`resize`
`useTargetMutation`	Tracks when targets are added or removed from the controller's scope, or their contents changed. Adds [target]TargetAdded , [target]TargetRemoved and [target]TargetChanged callback to your controller for each specified target.	`[target]TargetAdded` `[target]TargetRemoved` `[target]TargetChanged`
`useVisibility`	Tracks the page visibility and adds visible, invisible callbacks to your controller.	`visible` `invisible`
`useWindowFocus`	Tracks the window focus and adds focus, unfocs callbacks to your controller.	`focus` `unfocus`
`useWindowResize`	Tracks the size of the `window` object and adds a new lifecycle 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.

Animation

A set of mixin and controllers to build animations.

Mixin	Description
`useTransition`	Mixin or controller to apply classes to various stages of an element's transition.

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.
`useMeta`	Adds getters to easily access meta values.

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 ❤️ 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} 📖	_{Justin Coyne} 📖	_{Asger Behncke Jacobsen} 📖	_{Dan Callaghan} 📖
_{Konnor Rogers} 🐛 💻	_{Francisco Presencia} 📖	_{Takayuki Shimada} 🐛	_{Dylan Clarke} 💻 📖	_{Martin Tomov} 📖	_{Ryan Weaver} 📖 🐛	_{Adrien S} 🐛
_{Felix Albroscheit} 🐛	_{Guillaume Briday} 💻