/stimulus-use

A collection of composable behaviors for your Stimulus Controllers

Primary LanguageJavaScriptMIT LicenseMIT

A collection of composable behaviors for your Stimulus Controllers

npm version minified + gzip size types included types included


Stimulus Use Example


  • 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

  • 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 git@github.com: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 ❤️ by @adrienpoly and all these wonderful contributors (emoji key):


Jonathan Sundqvist

📖

Rui Freitas

📖

Nicolas Filzi

📖

Benjamin Darcet

📖

juancarlosasensio

📖

Marco Roth

🚇 💻

Philipp Daun

🐛

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