Getting Started
Install
Bun
bun install @m_three_ui/m3rippleOthers
npm
npm i @m_three_ui/m3ripplepnpm
pnpm add @m_three_ui/m3rippleYarn
yarn add @m_three_ui/m3rippleUse
Import <RippleContainer> component(based on <div />) and set props.
Example
import { RippleContainer } from '@m_three_ui/m3ripple'; //import it
import styles from './some_css_file.module.css';
const YourComponent = () => {
return (
<RippleContainer
isMaterial3 = {true}
beforeRippleFn = {(event) =>{}}
className = {styles.rippleContainer}
rippleColor = "hsla(29,81%,84%,0.15)"
sparklesColorRGB = "255 255 255"
opacity_level1 = "0.4"
opacity_level2 = "0.1"
sparklesMaxCount = 2048
divProps = {{}}
onMouseDown = {() => {}}
onTouchStart = {() => {}}
onTouchMove = {() => {}}
onMouseUp = {() => {}}
onTouchEnd = {() => {}}
onMouseLeave = {() => {}}
onTouchCancel = {() => {}}
>
<div className={styles.children} />
</RippleContainer>
);
};
export default YourComponent;| Property | optional | explanation | default | type |
|---|---|---|---|---|
isMaterial3 | yes | Whether to use ripple of Material 3 | true | boolean |
beforeRippleFn | yes | A function to be executed when a click occurs and just before the ripple is displayed (used for example to display a button shadow) | ()=>{} | (event: React.MouseEvent | React.TouchEvent) => void |
className | yes | Since RippleContainer is rendered as a div element, this is the ClassName of that div element. | "" | string |
children | yes | Child Elements of RippleContainer | undefined | ReactNode |
rippleColor | yes | Ripple Effect Colors. If transparency is not specified, the overlap will not be visible when multiple clicks are made. | "#ffffff35" | string |
sparklesColorRGB | yes | Specify sparkle color as space-separated RGB. Transparency cannot be specified. | "255 255 255" | string |
opacity_level1 | yes | Transparency just before the sparkle disappears. *The transparency when initially displayed is calculated by the current progress of the Ripple Effect | "0.2" | string |
opacity_level2 | yes | Transparency just before Sparkles disappear.Set after opacity_level1. | "0.1" | string |
sparklesMaxCount | yes | Total amount of dots representing sparkle. | 2048 | number |
divProps | yes | Since the RippleContainer is rendered as a Div element, you can pass Div element Props. | {} | Omit<ComponentPropsWithoutRef<'div'>, | 'className' | 'onMouseDown' | 'onMouseUp' | 'onMouseLeave' | 'onTouchStart' | 'onTouchMove' | 'onTouchEnd' | 'onTouchCancel'> |
onMouseDown, onMouseUp, onMouseLeave, onTouchStart, onTouchMove, onTouchEnd, onTouchCancel | yes | Props to handle events without interfering with the Ripple Effect implementation. one function is accepted. *Rather than using this, we recommend wrapping the RippleContainer itself in another HTML element and defining a handler for that element. | ()=>{} | (event) => void |
FAQ
The Ripple Effect looks broken. The ripple’s width and height seem to affect the layout of the child elements inside RippleContainer, as if the ripple doesn’t have position: absolute. What’s going on?
This is a known issue. It occurs when the CSS provided by the library fails to apply correctly.
As a workaround, please assign a custom class via the className prop on RippleContainer, and apply the following CSS manually:
.rippleContainer {
/* Workaround(m3ripple's css modules is not working) */
overflow: hidden;
position: relative;
z-index: 0;
& :global(.ripple) {
position: absolute;
border-radius: 100%;
z-index: -1;
transform: translateX(-50%) translateY(-50%);
pointer-events: none;
display: flex;
align-items: center;
justify-content: center;
user-select: none;
}
& :global(.sparkles_canvas) {
position: absolute;
user-select: none;
}
}This works only in environments where CSS is scoped using something like CSS Modules and supports :global().
If you’re not using such an environment, please use the following alternative instead.\
.rippleContainer {
/* Workaround(m3ripple's css modules is not working) */
overflow: hidden;
position: relative;
z-index: 0;
& .ripple {
position: absolute;
border-radius: 100%;
z-index: -1;
transform: translateX(-50%) translateY(-50%);
pointer-events: none;
display: flex;
align-items: center;
justify-content: center;
user-select: none;
}
& .sparkles_canvas {
position: absolute;
user-select: none;
}
}
When I wrap a RippleContainer with the a element, a blue box appears on tap in the mobile version of Chrome and the Ripple Effect is not visible. Is there any way to turn it off?
You can manipulate this effect using the -webkit-tap-highlight-color property. You can turn it off by specifying transparent.