# stimulus-use
> A collection of standard controllers and utilities for Stimulus
Latest version **0.53.1** (published 2026-09-04) · MIT license · 0 weekly downloads
## Install
```sh
npm install stimulus-use
pnpm add stimulus-use
yarn add stimulus-use
bun add stimulus-use
```
## Health
**Score 75/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.
Warnings: low downloads; pre 1.0.
## Facts
| | |
|---|---|
| Version | 0.53.1 |
| Published | 2026-09-04 |
| First published | 2020-03-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 156.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1682 |
| Author | Adrien Poly |
| Maintainers | adrienpoly, marcoroth |
## Links
- npm: https://www.npmjs.com/package/stimulus-use
- Repository: https://github.com/stimulus-use/stimulus-use
- Homepage: https://github.com/stimulus-use/stimulus-use#readme
- Issues: https://github.com/stimulus-use/stimulus-use/issues
- npm.io page: https://npm.io/package/stimulus-use
## Recent versions
- 0.53.1 (latest) — 2026-09-04
- 0.50.0-2 (beta) — 2021-09-28
- 0.16.2-0 (next) — 2020-11-03
- 0.53.0 — 2026-06-30
- 0.52.3 — 2024-12-15
- 0.52.2 — 2023-12-24
- 0.52.1 — 2023-10-15
- 0.52.0 — 2023-02-09
- 0.51.3 — 2023-01-14
- 0.51.2 — 2023-01-13
- 0.51.1 — 2022-11-22
- 0.51.0 — 2022-10-21
- 0.50.0 — 2022-05-10
- 0.50.0-1 — 2021-09-28
- 0.50.0-0 — 2021-09-24
- … 52 more at https://npm.io/package/stimulus-use/versions
## README
A collection of composable behaviors for your Stimulus Controllers
```js
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
```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
Read the full documentation at [stimulus-use.dev](https://stimulus-use.dev).
## 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`|
|[`useLazyLoad`](./docs/use-lazy-load.md) | Lazily loads an image once it scrolls into the viewport and adds **loading**, **loaded** callbacks to your controller.|`loading`
`loaded`|
|[`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
}
}
```
## Contributing
Want to help out? See [CONTRIBUTING.md](./CONTRIBUTING.md) to get started with local development.
## 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)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
---
_Source: https://npm.io/package/stimulus-use · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
