react-use-ripple fork version @mg-Song
A react hook to implement Material Design ripple overlays
What's Changed?
Add options
{
id <string> Default 'react-use-ripple' -> id is Essential, to customize startScale and endScale
startScale <number> Default 1
endScale <number> Default 10
}
Comment
The startScale and endScale were fixed, so made them to customize
but, there was an error that caused a duplicate style tag that was not good for
performance, and a unique id was required to resolve this issue.
Demo
Install
npm install --save @songmg/react-use-ripple
Usage
useRipple
only requires the ref of the DOM element that the ripple should be applied too.
import React from 'react';
import { useRipple } from '@songmg/react-use-ripple';
import { useRef } from 'react';
const App = () => {
const ref = useRef();
useRipple(ref);
return (
<button className="btn" ref={ref}>
Button
</button>
);
};
export default App;
Arguments
useRipple(ref [, options])
- ref
<RefObject<HTMLElement>>
- options
<Object>
- id
<string>
Default'react-use-ripple'
- disabled
<boolean>
Defaultfalse
- rippleColor*
<string>
Defaultrgba(0, 0, 0, 0.3)
- animationLength**
<number>
**Default**700
- rippleSize***
<number>
**Default**100
- startScale***
<number>
**Default**1
- endScale***
<number>
**Default**10
- excludedRefs****
<RefObject<HTMLElement>>[]
**Default**[]
- id
*
id
unique id for prevent duplicate style tags, id must be essential to set the scale *rippleColor
can be any valid css color that is supported by the targeted browsers**
animationLength
will always be in milliseconds***
rippleSize
will use the smallest value of the length, width, or specified size. if specifying a size, the unit will be in pixels.****
startScale
animation start-time scale value****
endScale
animation end-time scale value*****
excludedRefs
a list of child refs that should not cause a ripple when clicked
FAQ
Q. Can useRipple
be used more than once in a component?
A. useRipple
can be used as many times as neccessary inside a component.
Q. Does useRipple
support SSR?
A. Yup! Thanks to a recent PR, useRipple
now supports SSR (as of version 1.4.0)
Q. Can the useRipple
hook be conditionally rendered?
A. No. Keep the rules-of-hooks in mind when using use useRipple
and do not conditionally render it.
Q. What happens when the JSX with the ref is conditionally rendered? Will the ripple still work when the component mounts?
A. useRipple
can handle null references, so if an element using a the ripple effect is conditionally rendered, the effect will applied when the component mounts.
Q. How does adding a ripple to an element affect its css?
A. useRipple
does two things to an element's css:
- If an element's position is not set (i.e. its position is
initial
orstatic
) thanposition: relative
is added to the element. -
useRipple
sets the overflow of the element tohidden
, to prevent the ripple from extending outside the element.
NOTE: If your using child or descendant selectors to style span
elements, it may affect the css of the ripple. To avoid this, use specificity to target span elements that you wish to style.
License
MIT © Charles Badger