@songmg/react-use-ripple v0.0.5

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> Default false
  • rippleColor* <string> Default rgba(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 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 or static) than position: relative is added to the element.
• useRipple sets the overflow of the element to hidden, 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