# useripple

> A React Hook for adding ripple effect

Latest version **1.1.1** (published 2025-07-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install useripple
pnpm add useripple
yarn add useripple
bun add useripple
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2025-07-11 |
| First published | 2019-06-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 9.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 23 |
| Author | Robert Kirsz |
| Maintainers | robertkirsz |
| Keywords | react, hooks, ripple |

## Links

- npm: https://www.npmjs.com/package/useripple
- Repository: https://github.com/robertkirsz/useripple
- Homepage: https://github.com/robertkirsz/useripple#readme
- Issues: https://github.com/robertkirsz/useripple/issues
- npm.io page: https://npm.io/package/useripple

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.1.1 (latest) — 2025-07-11
- 1.1.0 — 2025-07-11
- 1.0.4 — 2022-06-26
- 1.0.3 — 2020-09-29
- 1.0.2 — 2020-04-29
- 1.0.1 — 2019-09-13
- 1.0.0 — 2019-06-19
- 0.3.0 — 2019-06-19
- 0.2.0 — 2019-06-19
- 0.1.0 — 2019-06-18

## README

<div align="center">
  <img alt="useRipple" src="animation.gif" width="240" />
  <br />
  <br />
  <a href="https://codesandbox.io/s/useripple-example-zt9ou" target="_blank">
    <img src="https://codesandbox.io/static/img/play-codesandbox.svg">
  </a>
</div>

## About

`useRipple` is a [React Hook](https://reactjs.org/docs/hooks-intro.html) that adds an animated ripple effect to a clicked element.

## Usage

##### Step 1 - install the module

`npm install useripple`

##### Step 2 - add CSS keyframes

```css
@keyframes useRippleAnimation {
  to {
    transform: scale(15);
    opacity: 0;
  }
}
```

☝️This is the animation that ripples use to ripple. It makes them grow and then disappear. Tweak it however you want and add to your stylesheet.

##### Step 3 - add the Hook

```js
import React from 'react'
import useRipple from 'useripple'

function App() {
  const [
    addRipple, // Attach this to any mouse event listener
    ripples // Render this to see the ripples
  ] = useRipple({
    // You can pass ripples` CSS here (no worries, it's optional)
    background: 'pink'
  })

  // Look how simple it is!
  return (
    <div onClick={addRipple} style={{ position: 'relative', overflow: 'hidden' }}>
      {ripples}
      Look at them ripplin'!
    </div>
  )
}
```

## FAQ

**Q:** Where should I attach `addRipple`?\
**A:** Any [MouseEvent](https://developer.mozilla.org/docs/Web/API/MouseEvent) listener will do, but your first bet is `onClick`, `onMouseDown` or `onMouseUp`.

**Q:** What if I want to do something more in my mouse event handler than just add ripples?\
**A:** That's simple! Instead of doing `<div onClick={addRipple}>` do `<div onClick={handleClick}>` and then declare `handleClick` function:

```js
function handleClick(event) {
  console.log("I'm gonna ripple!") // 👈 Do anything you want here
  addRipple(event) // Don't forget to feed `addRipple` with `event` 👌
}
```

**Q:** What is `ripples` variable?\
**A:** It's an array that gets filled with ripple components anytime you call `addRipple` function with a valid [MouseEvent](https://developer.mozilla.org/docs/Web/API/MouseEvent). Each ripple is an absolutely positioned `<div>`, so make sure their container has `position: relative;` or something other than default `static` (`overflow: hidden;` may come in handy too).

**Q:** What styles can I attach to ripples?\
**A:** Anything that's valid in React terms. See [here](https://github.com/robertkirsz/useripple/blob/master/src/index.js#L17-L28) what styles do ripples use. These are probably the ones you may want to override. If you want to override `animationName`, make sure you change it in Step 2 as well.

Enjoy! 💙

[![npm version](https://img.shields.io/npm/v/useripple.svg?color=blue)](https://www.npmjs.com/package/useripple) ![Bundle size](https://img.shields.io/bundlephobia/min/useripple.svg?color=blue) [![GitHub license](https://img.shields.io/npm/l/useripple.svg?color=blue)](https://github.com/robertkirsz/useripple/blob/master/LICENSE)

---
_Source: https://npm.io/package/useripple · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._