# @material/react-ripple

> Material Components React Ripple

Latest version **0.15.0** (published 2019-07-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @material/react-ripple
pnpm add @material/react-ripple
yarn add @material/react-ripple
bun add @material/react-ripple
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.15.0 |
| Published | 2019-07-22 |
| First published | 2018-05-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 178.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | abhiomkar, acdvorak, aprigogin, azakus, bicknellr, bonniez, bwobrien, kfranqueiro, lynnjepsen, material-admin, moog16, patrickrodee, williamernest |
| Keywords | mdc web react, material components react, material design, ripple |

## Links

- npm: https://www.npmjs.com/package/@material/react-ripple
- Repository: https://github.com/material-components/material-components-web-react
- Homepage: https://github.com/material-components/material-components-web-react#readme
- Issues: https://github.com/material-components/material-components-web-react/issues
- npm.io page: https://npm.io/package/@material/react-ripple

## Dependencies (4)

- [classnames](https://npm.io/package/classnames.md) ^2.2.6
- [@material/dom](https://npm.io/package/@material/dom.md) ^1.0.0
- [utility-types](https://npm.io/package/utility-types.md) ^3.2.1
- [@material/ripple](https://npm.io/package/@material/ripple.md) ^1.0.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.15.0 (latest) — 2019-07-22
- 0.14.1 — 2019-07-02
- 0.14.0 — 2019-06-25
- 0.13.0 — 2019-05-30
- 0.12.0 — 2019-05-01
- 0.11.0 — 2019-03-19
- 0.10.0 — 2019-02-19
- 0.9.0 — 2019-01-23
- 0.8.0 — 2018-12-28
- 0.7.1 — 2018-11-30
- 0.7.0 — 2018-11-20
- 0.6.2 — 2018-11-07
- 0.6.1 — 2018-10-25
- 0.6.0 — 2018-10-24
- 0.5.0 — 2018-09-25
- … 6 more at https://npm.io/package/@material/react-ripple/versions

## README

# React Ripple

A React version of an [MDC Ripple](https://github.com/material-components/material-components-web/tree/master/packages/mdc-ripple).

## Installation

```
npm install @material/react-ripple
```

## Usage

### Styles

with Sass:
```js
import '@material/react-ripple/index.scss';
```

You'll also need to include these sass mixins on the element. Please also refer to [Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-ripple/README.md#sass-apis) to customize further.

```sass
@import "@material/ripple/mdc-ripple.scss";

// refer to element in Javascript portion below
.ripple-icon-component {
  @include mdc-ripple-surface;
  @include mdc-ripple-radius-bounded;
  @include mdc-states;
  overflow: hidden;
}
```

with CSS:
```js
import '@material/react-ripple/dist/ripple.css';
```

### Javascript Instantiation

To wrap a component with the ripple HOC, please follow this example:

```js
import {withRipple} from '@material/react-ripple';

const Icon = (props) => {
  const {
    children,
    className = '',
    // You must call `initRipple` from the root element's ref. This attaches the ripple
    // to the element.
    initRipple,
    // include `unbounded` to remove warnings when passing `otherProps` to the
    // root element.
    unbounded,
    ...otherProps
  } = props;

  // any classes needed on your component needs to be merged with
  // `className` passed from `props`.
  const classes = `ripple-icon-component ${className}`;

  return (
    <div
      className={classes}
      ref={initRipple}
      {...otherProps}>
      {children}
    </div>
  );
};

const RippleIcon = withRipple(Icon);
```

Wrap your Icon component with the HOC `withRipple`, which returns a component
with a ripple capable surface.

### Typescript

If you're using TS, you will need to extend from the provided InjectedProps.

```js

import {withRipple, InjectedProps} from '@material/react-ripple';

interface IconProps extends InjectedProps<HTMLDivElement> {
  children?: React.ReactNode;
  className: string;
  initRipple: React.Ref<HTMLDivElement>;
  unbounded: boolean;
}

const Icon = (props) => {
  const {
    children,
    className = '',
    // You must call `initRipple` from the root element's ref. This attaches the ripple
    // to the element.
    initRipple,
    // include `unbounded` to remove warnings when passing `otherProps` to the
    // root element.
    unbounded,
    ...otherProps
  } = props;

  // any classes needed on your component needs to be merged with
  // `className` passed from `props`.
  const classes = `ripple-icon-component ${className}`;

  return (
    <div
      className={classes}
      ref={initRipple}
      {...otherProps}>
      {children}
    </div>
  );
};

const RippleIcon = withRipple<IconProps, HTMLDivElement>(Icon);
```

## Advanced Usage

### Ripple surface and ripple activator

You may want to apply the visual treatment (CSS classes and styles) for a ripple surface on one element, but have its activation rely on a different element. For example, putting a ripple on a `<div>` which will be activated by focusing on a child `<input>` element. We call the visual element the "ripple surface" and the activating element the "ripple activator".

The `initRipple` callback prop can take in an extra `activator` argument for the case where the ripple activator differs from the ripple surface. If the `activator` argument is not provided, the ripple surface will also serve as the ripple activator.

```js
import {withRipple} from '@material/react-ripple';

const MyInput = (props) => {
  const {
    rippleActivator,
    ...otherProps
  } = props;

  return (
    <input ref={rippleActivator} {...otherProps} />
  );
}

class MyComponent extends React.Component {
  rippleActivator = React.createRef();

  init = (el) => {
    this.props.initRipple(el /* surface */, this.rippleActivator.current /* activator */);
  }

  render() {
    const {
      className,
      initRipple,
      unbounded,
      ...otherProps
    } = this.props;

    return (
      <div
        className={`my-component ${className}`}
        ref={this.init}
        {...otherProps}>
        <MyInput rippleActivator={this.rippleActivator} />
      </div>
    );
  }
};

const MyRippledComponent = withRipple(MyComponent);
```

## Props

Prop Name | Type | Description
--- | --- | ---
unbounded | boolean | Ripple is unbounded if true.
disabled | n/a | Disables ripple if true.
style | object | Inline styles of root element.
className | string | Classes to appear on className attribute of root element.


## Sass Mixins

Sass mixins may be available to customize various aspects of the components. Please refer to the
MDC Web repository for more information on what mixins are available, and how to use them.

[Advanced Sass Mixins](https://github.com/material-components/material-components-web/blob/master/packages/mdc-ripple/README.md#sass-apis)

---
_Source: https://npm.io/package/@material/react-ripple · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._