stimulus-use

A collection of composable behaviors for your Stimulus Controllers

import { Controller } from '@hotwired/stimulus'
import { useIntersection, useResize } from 'stimulus-use'

export default class extends Controller {
  connect() {
    useIntersection(this)
    useResize(this)
  }

  appear(entry) {
    // new callback whenever the element appears.
    // entry is an IntersectionObserverEntry
  }

  disappear(entry) {
    // new callback whenever the element disappears.
  }

  resize({ width, height }) {
    // callback whenever the element gets resized
  }
}

• 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.
• Small: ~7k 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 compatibility.

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 2 (or below) you can use version 0.41.0. This version is designed to work with the stimulus npm package.

Using npm

npm i stimulus-use@0.41.0 stimulus@2.0.0

Using yarn

yarn add stimulus-use@0.41.0 stimulus@2.0.0

Documentation

Read the full documentation at stimulus-use.dev.

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
useLazyLoad	Lazily loads an image once it scrolls into the viewport and adds loading, loaded callbacks to your controller.	loading loaded
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, unfocus 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 <head> 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 '@hotwired/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
  }
}

Contributing

Want to help out? See CONTRIBUTING.md to get started with local development.

Contributors

Made with by @adrienpoly, @marcoroth 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	craisp	Gabriel	Donnie Flood	Óscar Carretero	Ikko Ashimine
Michael Coyne	Ollie Harridge	Leon Vogt	Thomas König	Scott	Daniel Rikowski	Marc Köhlbrugge
Leon Vogt	Ted H. Tran	Romain Monteil	Adam Jahnke	Kerrick Long	Alexander Brandon Coles

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