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
```