0
# Material Ripple
1
2
Material Ripple provides Material Design ink ripple interaction effects for web components. It implements the official Material Design specifications for touch feedback animations, offering both JavaScript-enabled and CSS-only fallback implementations for maximum compatibility.
3
4
## Package Information
5
6
- **Package Name**: @material/ripple
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript with Sass
9
- **Installation**: `npm install @material/ripple`
10
11
## Core Imports
12
13
```typescript
14
import { MDCRipple, MDCRippleFoundation } from "@material/ripple";
15
```
16
17
For individual imports:
18
19
```typescript
20
import { MDCRipple } from "@material/ripple/component";
21
import { MDCRippleFoundation } from "@material/ripple/foundation";
22
import { MDCRippleAdapter } from "@material/ripple/adapter";
23
import * as util from "@material/ripple/util";
24
import { cssClasses, strings, numbers } from "@material/ripple/constants";
25
```
26
27
CommonJS:
28
29
```javascript
30
const { MDCRipple, MDCRippleFoundation } = require("@material/ripple");
31
```
32
33
Sass imports:
34
35
```scss
36
@use "@material/ripple";
37
```
38
39
## Basic Usage
40
41
```typescript
42
import { MDCRipple } from "@material/ripple";
43
44
// Basic ripple attachment
45
const surface = document.querySelector('.my-surface');
46
const ripple = new MDCRipple(surface);
47
48
// Using static attachTo method
49
MDCRipple.attachTo(document.querySelector('.my-surface'));
50
51
// Unbounded ripple (like checkboxes/radio buttons)
52
const unboundedRipple = MDCRipple.attachTo(surface, { isUnbounded: true });
53
54
// Programmatic activation
55
ripple.activate();
56
ripple.deactivate();
57
```
58
59
CSS setup:
60
61
```scss
62
@use "@material/ripple";
63
64
.my-surface {
65
@include ripple.surface;
66
@include ripple.radius-bounded;
67
@include ripple.states;
68
}
69
```
70
71
## Architecture
72
73
Material Ripple is built around several key components:
74
75
- **MDCRipple Component**: Main JavaScript class providing ripple functionality
76
- **MDCRippleFoundation**: Core logic handling ripple state and animations
77
- **MDCRippleAdapter**: Interface for framework integration and DOM operations
78
- **CSS Variables System**: Dynamic styling using CSS custom properties
79
- **Sass Mixins**: Comprehensive styling system for different ripple configurations
80
- **Event System**: Touch, mouse, keyboard, and focus event handling
81
82
## Capabilities
83
84
### Component API
85
86
Primary JavaScript interface for attaching and controlling ripples programmatically. Provides methods for activation, deactivation, and configuration.
87
88
```typescript { .api }
89
class MDCRipple extends MDCComponent<MDCRippleFoundation> {
90
static attachTo(root: Element, opts?: MDCRippleAttachOpts): MDCRipple;
91
static createAdapter(instance: MDCRippleCapableSurface): MDCRippleAdapter;
92
93
unbounded: boolean;
94
disabled: boolean;
95
96
activate(): void;
97
deactivate(): void;
98
layout(): void;
99
}
100
```
101
102
[Component API](./component.md)
103
104
### Foundation API
105
106
Core ripple logic and state management. Handles activation/deactivation animations, event coordination, and CSS variable updates.
107
108
```typescript { .api }
109
class MDCRippleFoundation extends MDCFoundation<MDCRippleAdapter> {
110
static readonly cssClasses: typeof cssClasses;
111
static readonly strings: typeof strings;
112
static readonly numbers: typeof numbers;
113
static readonly defaultAdapter: MDCRippleAdapter;
114
115
activate(evt?: Event): void;
116
deactivate(): void;
117
layout(): void;
118
setUnbounded(unbounded: boolean): void;
119
handleFocus(): void;
120
handleBlur(): void;
121
}
122
```
123
124
[Foundation API](./foundation.md)
125
126
### Adapter Interface
127
128
Integration interface for custom frameworks and components. Defines required methods for DOM manipulation, event handling, and CSS updates.
129
130
```typescript { .api }
131
interface MDCRippleAdapter {
132
browserSupportsCssVars(): boolean;
133
isUnbounded(): boolean;
134
isSurfaceActive(): boolean;
135
isSurfaceDisabled(): boolean;
136
addClass(className: string): void;
137
removeClass(className: string): void;
138
containsEventTarget(target: EventTarget | null): boolean;
139
updateCssVariable(varName: string, value: string | null): void;
140
computeBoundingRect(): DOMRect;
141
getWindowPageOffset(): MDCRipplePoint;
142
}
143
```
144
145
[Adapter Interface](./adapter.md)
146
147
### Sass Styling System
148
149
Comprehensive mixin system for styling different ripple configurations, including bounded/unbounded ripples and various interaction states.
150
151
```scss { .api }
152
@mixin surface();
153
@mixin radius-bounded($radius: 100%);
154
@mixin radius-unbounded($radius: 100%);
155
@mixin states($color, $has-nested-focusable-element: false);
156
@mixin states-base-color($color);
157
@mixin states-opacities($opacity-map, $has-nested-focusable-element: false);
158
159
@function states-opacity($color, $state);
160
```
161
162
[Sass API](./sass.md)
163
164
### Utility Functions
165
166
Helper functions for CSS variable support detection and event coordinate normalization across different input types.
167
168
```typescript { .api }
169
function supportsCssVariables(windowObj: typeof globalThis, forceRefresh?: boolean): boolean;
170
function getNormalizedEventCoords(evt: Event | undefined, pageOffset: MDCRipplePoint, clientRect: DOMRect): MDCRipplePoint;
171
```
172
173
[Utilities](./utilities.md)
174
175
## Types
176
177
### Package Types
178
179
```typescript { .api }
180
interface MDCRippleAttachOpts {
181
isUnbounded?: boolean;
182
}
183
184
interface MDCRippleCapableSurface {
185
root: Element;
186
unbounded?: boolean;
187
disabled?: boolean;
188
}
189
190
interface MDCRipplePoint {
191
x: number;
192
y: number;
193
}
194
195
type MDCRippleFactory = (el: Element, foundation?: MDCRippleFoundation) => MDCRipple;
196
```
197
198
### External Base Types
199
200
From `@material/base`:
201
202
```typescript { .api }
203
abstract class MDCComponent<FoundationType extends MDCFoundation> {
204
readonly root: Element;
205
destroy(): void;
206
static attachTo(root: Element): MDCComponent<any>;
207
}
208
209
abstract class MDCFoundation<AdapterType> {
210
protected adapter: AdapterType;
211
init(): void;
212
destroy(): void;
213
}
214
```
215
216
From `@material/base/types`:
217
218
```typescript { .api }
219
type EventType = keyof HTMLElementEventMap;
220
type SpecificEventListener<K extends EventType> = (event: HTMLElementEventMap[K]) => void;
221
```