https://github.com/balazshevesi/react-ripples-continued
⚛️ The material design ripple effect for react made simple yet customisable. `npm i react-ripples-continued`
https://github.com/balazshevesi/react-ripples-continued
button-animation components-library documentation front-end-engineering javascript javascript-library material-ui mit-license npm-package open-source react-js ripple-effect web-development
Last synced: about 2 months ago
JSON representation
⚛️ The material design ripple effect for react made simple yet customisable. `npm i react-ripples-continued`
- Host: GitHub
- URL: https://github.com/balazshevesi/react-ripples-continued
- Owner: balazshevesi
- License: mit
- Created: 2023-10-07T11:49:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-28T16:37:15.000Z (over 2 years ago)
- Last Synced: 2025-04-14T00:52:32.918Z (about 1 year ago)
- Topics: button-animation, components-library, documentation, front-end-engineering, javascript, javascript-library, material-ui, mit-license, npm-package, open-source, react-js, ripple-effect, web-development
- Language: TypeScript
- Homepage: https://balazs-topg.github.io/react-ripples-continued/
- Size: 1.92 MB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
React Ripples Continued 🌊
Ripple effect for react made simple⚛️
---
React Ripples Continued is a
[react](https://react.dev/) component library for creating ripples effects.
This repository contains
- [the npm package](https://www.npmjs.com/package/react-ripples-continued) ([view code](/package/))
- [the documentaton](#documentation) ([view file](/README.md))
- [the website that showcases the components](https://balazs-topg.github.io/react-ripples-continued/) ([view code](/src/))
# Contents
- [Documentation](#-documentation)
- [Installation](#-installation)
- [Usage](#-usage)
- [Props](#-props)
- [Ripples Component](#ripples-component)
- [RippleSurface Component](#ripplesurface-component)
- [Internal Workings](#-internal-workings)
- [Server Side Rendering](#-server-side-rendering)
- [How To Contribute](#-how-to-contribute)
- [License](#-license)
# 📖 Documentation
## 💾 Installation
Run this [npm](https://docs.npmjs.com/) command in the directory of your react application
`npm i react-ripples-continued`
## 😃 Usage
This library includes two components: Ripples, and RippleSurface.
The Ripples component creates a ripple effect. Note that the parent container should have overflow: "hidden" and position: "relative" for proper functionality.
```javascript
import { Ripples } from "react-ripples-continued";
export default function Button() {
return (
react ripples 🎉
);
}
```
RippleSurface Component
The RippleSurface component is a wrapper that simplifies implementing the ripple effect on various elements.
```javascript
import { RippleSurface } from "react-ripples-continued";
export default function CustomComponent() {
return (
react ripples 🎉
);
}
```
## 🏠 Props
### Ripples Component
All props are optional
#### `on`
- Type: `"click" | "mouseDown" | "clickAndMouseDown" | "hover"`
- Default: `"click"`
Determines the event that triggers the ripple effect.
#### `color`
- Type: `string`
- Default: `"white"`
Sets the color of the ripple effect.
#### `opacity`
- Type: `number`
- Default: `1`
Sets the opacity of the ripple effect. Accepts values between `0` (completely transparent) and `1` (completely opaque).
#### `blur`
- Type: `number`
- Default: `0`
Sets the blur amount for the ripple effect. The value is in `rem` units.
#### `duration`
- Type: `number`
- Default: `500`
Determines the duration of the ripple animation in milliseconds.
#### `fillAndHold`
- Type: `boolean`
- Default: `false`
When set to `true`, the ripple effect will fill the container and hold its position until a mouse up event occurs.
#### `optimize`
- Type: `boolean`
- Default: `false`
When set to `true`, the ripple elements will be removed from the DOM after the animation completes. This can be useful for performance optimization in scenarios with frequent ripple triggers, but it's set to false by default, since it can introduce some wierd behaviour.
#### `rippleElement`
- Type: `React.ReactNode`
- Default: `undefined`
When handed JSX it will display that JSX inside the ripple. Keep in mind that you probably want to lower the opacticy of the color prop or set `color=""` if you use `rippleElement`
The `rippleElement` prop can be used to do create some pretty cool stuff!
#### `zIndex`
- Type: `number`
- Default: `undefined`
### RippleSurface Component
All props are optional
#### `tag`
- Type: `React.ReactNode`
- Default: `HtmlTagName`
#### `children`
- Type: `React.ReactNode`
- Default: `ReactNode`
#### `disableDefaultStyling`
- Type: `boolean`
- Default: `false`
When set to true, default styling (overflow and position) is not applied.
#### `rippleFromBehind`
- Type: `boolean`
- Default: `false`
When set to true, the ripple effect appears behind the content.
Note: this will also wrap the "children" in a div
#### `forwardedRef`
- Type: `boolean`
- Default: `any`
Will forward the red
#### `onClick`, `onSubmit`, `onInput`
Event handlers
#### `rippleProps`
- Type: `RipplesInterface`
Props to be passed to the Ripples component.
## 🛠 Internal Workings
#### `addRipple`
This internal function is responsible for creating and animating the ripple effect based on the provided parameters.
This function is not react specific (except ReactDOM.createRoot for prasing JSX/createElement calls to js DOM operations), so it could quite easily be adpated for use with solid, vue, svelte, angular, or any other framework.
## 🖥 Server Side Rendering
This library was built for server side use in mind, primarily for [next](https://nextjs.org/). Both of the components are tagged with ["use clients"](https://react.dev/reference/react/use-client) to ensure it works.
## 👏 How to contribute
All types of contributions are welcome! Feel free to open issues, or pull requests or whatever you feel like.
## 📄 License
This library is [MIT licensed](/LICENSE).