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

  • useApplication, ApplicationController — supercharged controller for your application.

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

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

Acknowledgments

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

🚧 in construction

matrix

badge