https://github.com/stimulus-use/stimulus-use

A collection of composable behaviors for your Stimulus Controllers
https://github.com/stimulus-use/stimulus-use

hotwire stimulus stimulus-controller stimulus-use stimulusjs turbo typescript

Last synced: 9 months ago
JSON representation

A collection of composable behaviors for your Stimulus Controllers

Host: GitHub
URL: https://github.com/stimulus-use/stimulus-use
Owner: stimulus-use
License: mit
Created: 2020-05-18T06:34:53.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2025-03-14T21:24:27.000Z (11 months ago)
Last Synced: 2025-05-12T13:17:26.307Z (9 months ago)
Topics: hotwire, stimulus, stimulus-controller, stimulus-use, stimulusjs, turbo, typescript
Language: JavaScript
Homepage: https://stimulus-use.github.io/stimulus-use
Size: 4.5 MB
Stars: 1,616
Watchers: 14
Forks: 70
Open Issues: 37
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-hotwire - stimulus-use - A collection of composable behaviors for your Stimulus controllers. (**Awesome Hotwire** [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome) / Stimulus)

README

          


  





  **A collection of composable behaviors for your Stimulus Controllers**

  [![npm version](https://badgen.net/npm/v/stimulus-use)](https://npmjs.com/package/stimulus-use)

  [![minified + gzip size](https://badgen.net/bundlephobia/minzip/stimulus-use)](https://bundlephobia.com/result?p=stimulus-use)

  ![types included](https://badgen.net/npm/types/tslib)

  ![license](https://badgen.net/npm/license/stimulus-use)

  ![Sauce test status](./docs/assets/example-buildstatus-badge.png)








  






- **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` compability.

#### Using npm

```bash

npm i stimulus-use @hotwired/stimulus

```

#### Using yarn

```bash

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

```bash

npm i stimulus-use@0.41.0 stimulus@2.0.0

```

#### Using yarn

```bash

yarn add stimulus-use@0.41.0 stimulus@2.0.0

```

## Documentation

We got you covered 👉 [stimulus-use.github.io/stimulus-use](https://stimulus-use.github.io/stimulus-use/#/)

## Mixins

### Observers

  This set of mixins is built around the [`Observer APIs`](https://developer.mozilla.org/en-US/docs/Web/API) and custom events to enhance your controllers with new behaviors.

  | Mixin | Description | NEW Callbacks |

  |-----------------------|-------------|---------------------|

  |[`useClickOutside`](./docs/use-click-outside.md)|Tracks the clicks outside of the element and adds a new lifecycle callback **clickOutside**.|`clickOutside`|

  |[`useHotkeys`](./docs/use-hotkeys.md)|Registers hotkeys using the [hotkeys-js](https://wangchujiang.com/hotkeys-js/) library and binds them to handler methods||

  |[`useHover`](./docs/use-hover.md)|Tracks the user's mouse movements over an element and adds **mouseEnter** and **mouseLeave** callbacks to your controller.|`mouseEnter` `mouseLeave`|

  |[`useIdle`](./docs/use-idle.md)| Tracks if the user is idle on your page and adds **away** and **back** callbacks to your controller.|`away` `back`|

  |[`useIntersection`](./docs/use-intersection.md) | Tracks the element's intersection and adds **appear**, **disappear** callbacks to your controller.|`appear` `disappear`|

  |[`useMatchMedia`](./docs/use-match-media.md) | Tracks if the window matches a media query string.| `is[Name]`, `not[Name]` and `[name]Changed`|

  |[`useMutation`](./docs/use-mutation.md) | Tracks mutations on an element, its attributes and/or subtree. Adds a **mutate** callback to your controller.|`mutate`|

  |[`useResize`](./docs/use-resize.md)|Tracks the element's size and adds a new lifecycle callback **resize**.|`resize`|

  |[`useTargetMutation`](./docs/use-target-mutation.md) | 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`](./docs/use-visibility.md) | Tracks the page visibility and adds **visible**, **invisible** callbacks to your controller.|`visible` `invisible`|

  |[`useWindowFocus`](./docs/use-window-focus.md) | Tracks the window focus and adds **focus**, **unfocus** callbacks to your controller.|`focus` `unfocus`|

  |[`useWindowResize`](./docs/use-window-resize.md)| 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`](./docs/use-debounce.md)|Adds the ability to specify an array "debounces" of functions to   debounce.|

  |[`useMemo`](./docs/use-memo.md)|Memoize expensive getters by mixing in `useMemo` and adding a static   `memos` array.|

  |[`useThrottle`](./docs/use-throttle.md)|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`](./docs/use-transition.md)|Mixin or controller to apply classes to various stages of an element's transition.|

### Application

  | Mixin | Description |

  |------|-------------|

  |[`useApplication, ApplicationController`](./docs/application-controller.md)| supercharged controller for your application.|

  |[`useDispatch`](./docs/use-dispatch.md)|Adds a dispatch helper function to emit custom events. Useful to communicate between different controllers.|

  |[`useMeta`](./docs/use-meta.md)|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.

```js

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.

```js

import { IntersectionController } from 'stimulus-use'

export default class extends IntersectionController {

  appear(entry) {

    // triggered when the element appears within the viewport

  }

}

```

## Development

- Fork the project locally

- `yarn install`

- `yarn start` - to run the local dev server with examples

- `yarn test` - to run the unit tests

- `yarn lint` - to run the linter with ESLint

- `yarn format` - to format changes with Prettier

- `yarn build` - to bundle the app into static files for production

## Contributors ✨

Made with :heart: by [@adrienpoly](https://twitter.com/adrienpoly), [@marcoroth](https://twitter.com/marcoroth_) and all these wonderful contributors ([emoji key](https://github.com/kentcdodds/all-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}
💻

    

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

## Acknowledgments

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

[![Testing Powered By SauceLabs](https://opensource.saucelabs.com/images/opensauce/powered-by-saucelabs-badge-white.png?sanitize=true "Testing Powered By SauceLabs")](https://saucelabs.com)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/stimulus-use/stimulus-use

Awesome Lists containing this project

README