DocsComponents

Ripple

Touch feedback that grows from the point of interaction.

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/ripple.json

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

The host needs relative positioning and overflow-hidden. Buttons and several other Toolbox controls already include ripple feedback; no extra wrapper is needed for them.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

useRipple owns short-lived pointer feedback internally. Spread its event handlers onto your interactive element and render its ripple output inside that element. The hook does not perform an application action or manage selection.

rippleFactory(options)(Component) and Ripple(options)(Component) are optional decorators. Define the enhanced component outside render. Enhanced components accept RippleProps in addition to their original props.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`rippleFactory`

A decorator factory: pass these options, then the component to enhance. Create the enhanced component outside render.

Property	Type	Default
`centered`	`boolean`	`—`
`className`	`string`	`—`
`disabled`	`boolean`	`—`
`multiple`	`boolean`	`—`
`spread`	`number`	`—`
`classNames`	`RippleTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`RippleTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`ripple`	`boolean`	`—`
`passthrough`	`boolean`	`—`

Callbacks

Property	Type	Default
`onRippleEnded`	`TransitionEventHandler<HTMLSpanElement>`	`—`
`onMouseDown`	`MouseEventHandler<HTMLElement>`	`—`
`onTouchStart`	`TouchEventHandler<HTMLElement>`	`—`
`onTouchEnd`	`TouchEventHandler<HTMLElement>`	`—`
`onTouchCancel`	`TouchEventHandler<HTMLElement>`	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

ripple
rippleActive
rippleRestarting
rippleWrapper

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`Ripple`

A decorator factory: pass these options, then the component to enhance. Create the enhanced component outside render.

Property	Type	Default
`centered`	`boolean`	`—`
`className`	`string`	`—`
`disabled`	`boolean`	`—`
`multiple`	`boolean`	`—`
`spread`	`number`	`—`
`classNames`	`RippleTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`RippleTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`ripple`	`boolean`	`—`
`passthrough`	`boolean`	`—`

Callbacks

Property	Type	Default
`onRippleEnded`	`TransitionEventHandler<HTMLSpanElement>`	`—`
`onMouseDown`	`MouseEventHandler<HTMLElement>`	`—`
`onTouchStart`	`TouchEventHandler<HTMLElement>`	`—`
`onTouchEnd`	`TouchEventHandler<HTMLElement>`	`—`
`onTouchCancel`	`TouchEventHandler<HTMLElement>`	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

ripple
rippleActive
rippleRestarting
rippleWrapper

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`useRipple`

Call this hook inside a React component. Its argument properties are listed below.

Property	Type	Default
`centered`	`boolean`	`false`
`className`	`string`	`—`
`disabled`	`boolean`	`false`
`multiple`	`boolean`	`true`
`spread`	`number`	`2`
`classNames`	`RippleTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`RippleTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`ripple`	`boolean`	`true`

Callbacks

Property	Type	Default
`onRippleEnded`	`TransitionEventHandler<HTMLSpanElement>`	`—`
`onMouseDown`	`MouseEventHandler<HTMLElement>`	`—`
`onTouchStart`	`TouchEventHandler<HTMLElement>`	`—`
`onTouchEnd`	`TouchEventHandler<HTMLElement>`	`—`
`onTouchCancel`	`TouchEventHandler<HTMLElement>`	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

ripple
rippleActive
rippleRestarting
rippleWrapper

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/ripple.

RippleProps

tsx

interface RippleProps {
  disabled?: boolean;
  ripple?: boolean;
  rippleCentered?: boolean;
  rippleClassName?: string;
  rippleMultiple?: boolean;
  rippleSpread?: number;
  onRippleEnded?: TransitionEventHandler<HTMLSpanElement>;
}

RippleTheme

tsx

type RippleTheme = Partial<Record<'ripple' | 'rippleActive' | 'rippleRestarting' | 'rippleWrapper', string>>;

RippleClassNames

tsx

type RippleClassNames = RippleTheme;

RippleOptions

tsx

interface RippleOptions {
  centered?: boolean;
  className?: string;
  disabled?: boolean;
  multiple?: boolean;
  spread?: number;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: RippleTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: RippleTheme;
  ripple?: boolean;
  onRippleEnded?: TransitionEventHandler<HTMLSpanElement>;
  onMouseDown?: MouseEventHandler<HTMLElement>;
  onTouchStart?: TouchEventHandler<HTMLElement>;
  onTouchEnd?: TouchEventHandler<HTMLElement>;
  onTouchCancel?: TouchEventHandler<HTMLElement>;
}

RippleBehavior

tsx

interface RippleBehavior {
  ripple: ReactNode;
  onMouseDown: MouseEventHandler<HTMLElement>;
  onTouchStart: TouchEventHandler<HTMLElement>;
  onTouchEnd: TouchEventHandler<HTMLElement>;
  onTouchCancel: TouchEventHandler<HTMLElement>;
}

Material guidelines

Use ink feedback to connect a press to the surface receiving it. Keep the effect contained by that surface’s shape.
Ripple is visual feedback, not an interaction by itself. Attach it to an accessible button or link and retain visible keyboard focus.

Material Design 1: Material motion