Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/asplunds/use-ripple
Fully customizable, lightweight React hook for implementing Google's Material UI style ripple effect
https://github.com/asplunds/use-ripple
Last synced: 3 months ago
JSON representation
Fully customizable, lightweight React hook for implementing Google's Material UI style ripple effect
- Host: GitHub
- URL: https://github.com/asplunds/use-ripple
- Owner: asplunds
- Created: 2022-02-12T18:18:55.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-10-06T07:17:57.000Z (over 1 year ago)
- Last Synced: 2024-11-08T12:06:28.625Z (4 months ago)
- Language: TypeScript
- Size: 70.3 KB
- Stars: 24
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# useRipple - Material UI ripple effect
Fully customizable, lightweight React hook for implementing Google's Material UI style ripple effect
[](https://codesandbox.io/s/great-nash-zhyfm?fontsize=14&hidenavigation=1&theme=dark)
## Installation
```
npm install use-ripple-hook
```
or
```
yarn add use-ripple-hook
```
## Usage
```tsx
import React from "react";
import useRipple from "use-ripple-hook";
function Button() {
const [ripple, event] = useRipple();
return (
Default Ripple
);
}
```
## Options
### Default options
```ts
useRipple({
duration: 450,
color: "rgba(255, 255, 255, .3)",
cancelAutomatically: false,
className: "__useRipple--ripple",
containerClassName: "__useRipple--ripple-container",
ignoreNonLeftClick: true,
timingFunction: "cubic-bezier(.42,.36,.28,.88)",
disabled: false,
ref: internalRef,
onSpawn: undefined,
});
```
### Options reference
| Property | Description | Type | Default | Optional |
| --------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------- | ------------------------------- | -------- |
| `duration` | Duration in milliseconds | `number` | `450` | ✔️ |
| `color` | Color of the ripple effect | `string` | `rgba(255, 255, 255, .3)` | ✔️ |
| `cancelAutomatically` | If `true`, the ripple will begin to cancel after 40% of the duration | `boolean` | `false` | ✔️ |
| `className` | The ripple element's class name | `string` | `__useRipple--ripple` | ✔️ |
| `containerClassName` | The container element for the ripples | `string` | `__useRipple--ripple-container` | ✔️ |
| `ignoreNonLeftClick` | If `false`, non left click events such as right click and middle click will also trigger ripples | `boolean` | `true` | ✔️ |
| `timingFunction` | Transition timing function of the transform animation | `string` | `cubic-bezier(.42,.36,.28,.88)` | ✔️ |
| `disabled` | If `true`, no ripples will be spawned | `boolean` | `false` | ✔️ |
| `ref` | Optional outside ref, if unset, internal ref will be used | `React.RefObject` | `undefined` | ✔️ |
| `onSpawn` | A callback which is triggered when a ripple is spawned | [options.onspawn](#optionsonspawn) | `undefined` | ✔️ |
### `options.onSpawn`
**Type**
```ts
type OnSpawnCB = (ctx: {
/** the ripple element */
readonly ripple: HTMLDivElement;
/** cancels the current ripple animation */
readonly cancelRipple: () => void;
/** the ref to the ripple host element */
readonly ref: React.RefObject;
/** the event that triggered the ripple (ts: casting required) */
readonly event: unknown;
/** the ripple container element */
readonly container: HTMLDivElement;
}) => void;
```
**Example**
```js
useRipple({
/* ... */
onSpawn: ({
ripple, ref, event, container
}) => {
console.table({ ripple, ref, event, container });
}
});
```
## Perfect circle
As demonstrated in the below GIF, useRipple adjusts the circle size to always for the host element's border box.
## Higher order function (HOF)
If you want to memoize a configuration for your ripple you can use the built in `customRipple()` function.
You can override the options you memoized for your custom ripple hook. The two options will be merged.
### Usage
```tsx
import { customRipple } from "use-ripple-hook";
const useMyRipple = customRipple({
color: "rgb(144, 238, 144, .7)",
duration: 700,
});
function Button() {
const [ripple, event] = useMyRipple({}); // Optionally override previous config
return (
Memoized Ripple
);
}
```
This is useful if you want to avoid repetition in your code or if you want multiple different ripple effects for different components.
## Examples
For examples of useRipple usage please click here.
## Dos and don'ts
### ✔ Do this:
Using components 👍
```jsx
import React from "react";
import useRipple from "use-ripple-hook";
function App() {
return (
<>
>
)
}
function Button({ color }) {
const [ripple, event] = useRipple({ color });
return (
Button
);
}
```
### ❌ Don't do this:
Sharing references 👎
```jsx
import React from "react";
import useRipple from "use-ripple-hook";
function App() {
const [ripple, event] = useRipple();
/* This will NOT work! Do not do this */
return (
<>
Button
Button
>
)
}
```
## Contributing
Contributions of any form are appreciated, opening issues on the Github repository as well as creating pull requests are both welcomed for anyone to do.