0
# Component API
1

2
The MDCRipple component is the primary JavaScript interface for attaching and controlling ripples. It extends MDCComponent and provides methods for programmatic ripple control.
3

4
## Capabilities
5

6
### MDCRipple Class
7

8
Main ripple component providing programmatic ripple control.
9

10
```typescript { .api }
11
/**
12
 * Main ripple component providing programmatic ripple control
13
 * Extends MDCComponent to provide component lifecycle management
14
 */
15
class MDCRipple extends MDCComponent<MDCRippleFoundation> implements MDCRippleCapableSurface {
16
  /** Attach ripple to element with optional configuration */
17
  static attachTo(root: Element, opts?: MDCRippleAttachOpts): MDCRipple;
18
  
19
  /** Create adapter for custom framework integration */
20
  static createAdapter(instance: MDCRippleCapableSurface): MDCRippleAdapter;
21
  
22
  /** Whether ripple extends beyond element bounds */
23
  unbounded: boolean;
24
  
25
  /** Whether ripple is disabled */
26
  disabled: boolean;
27
  
28
  /** Programmatically activate the ripple */
29
  activate(): void;
30
  
31
  /** Programmatically deactivate the ripple */
32
  deactivate(): void;
33
  
34
  /** Recompute ripple dimensions and positions */
35
  layout(): void;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { MDCRipple } from "@material/ripple";
43

44
// Basic attachment
45
const surface = document.querySelector('.my-button');
46
const ripple = new MDCRipple(surface);
47

48
// Using static method
49
const ripple2 = MDCRipple.attachTo(document.querySelector('.my-surface'));
50

51
// Unbounded ripple (for checkboxes, radio buttons)
52
const unboundedRipple = MDCRipple.attachTo(surface, { isUnbounded: true });
53

54
// Configure properties
55
ripple.unbounded = true;
56
ripple.disabled = false;
57

58
// Programmatic control
59
ripple.activate();
60
setTimeout(() => ripple.deactivate(), 300);
61

62
// Recompute layout (useful after dynamic size changes)
63
ripple.layout();
64
```
65

66
### Static Methods
67

68
#### attachTo
69

70
Convenience method to create and attach a ripple to an element.
71

72
```typescript { .api }
73
/**
74
 * Attach ripple to element with optional configuration
75
 * @param root - Element to attach ripple to
76
 * @param opts - Optional configuration including unbounded setting
77
 * @returns New MDCRipple instance
78
 */
79
static attachTo(root: Element, opts?: MDCRippleAttachOpts): MDCRipple;
80
```
81

82
#### createAdapter
83

84
Creates a standard adapter implementation for MDCRippleCapableSurface instances.
85

86
```typescript { .api }
87
/**
88
 * Create adapter for custom framework integration
89
 * @param instance - Object implementing MDCRippleCapableSurface
90
 * @returns Configured MDCRippleAdapter instance
91
 */
92
static createAdapter(instance: MDCRippleCapableSurface): MDCRippleAdapter;
93
```
94

95
**Usage Example:**
96

97
```typescript
98
import { MDCRipple, MDCRippleFoundation } from "@material/ripple";
99

100
class MyCustomComponent {
101
  constructor(element) {
102
    this.root = element;
103
    this.unbounded = false;
104
    this.disabled = false;
105
    
106
    // Create custom foundation with mixed adapter
107
    const foundation = new MDCRippleFoundation({
108
      ...MDCRipple.createAdapter(this),
109
      // Override specific methods for custom behavior
110
      isSurfaceActive: () => this.isActive,
111
    });
112
    
113
    this.ripple = new MDCRipple(this.root, foundation);
114
  }
115
}
116
```
117

118
### Properties
119

120
#### unbounded
121

122
Controls whether the ripple is bounded by the element's dimensions.
123

124
```typescript { .api }
125
/**
126
 * Whether ripple extends beyond element bounds
127
 * - Bounded ripples (false): Clipped by element overflow:hidden
128
 * - Unbounded ripples (true): Extend beyond element bounds
129
 */
130
unbounded: boolean;
131
```
132

133
#### disabled
134

135
Controls whether the ripple responds to interactions.
136

137
```typescript { .api }
138
/**
139
 * Whether ripple is disabled
140
 * When true, ripple will not activate on user interactions
141
 */
142
disabled: boolean;
143
```
144

145
### Instance Methods
146

147
#### activate
148

149
Programmatically triggers ripple activation animation.
150

151
```typescript { .api }
152
/**
153
 * Programmatically activate the ripple
154
 * Triggers the same animation as user interaction
155
 */
156
activate(): void;
157
```
158

159
#### deactivate
160

161
Programmatically triggers ripple deactivation animation.
162

163
```typescript { .api }
164
/**
165
 * Programmatically deactivate the ripple
166
 * Completes the ripple animation cycle
167
 */
168
deactivate(): void;
169
```
170

171
#### layout
172

173
Recomputes ripple dimensions and positions.
174

175
```typescript { .api }
176
/**
177
 * Recompute ripple dimensions and positions
178
 * Call this when element size or position changes dynamically
179
 */
180
layout(): void;
181
```
182

183
## Integration Examples
184

185
### Basic Button
186

187
```typescript
188
import { MDCRipple } from "@material/ripple";
189

190
// HTML: <button class="mdc-button">Click me</button>
191
const button = document.querySelector('.mdc-button');
192
const ripple = new MDCRipple(button);
193
```
194

195
### Checkbox/Radio (Unbounded)
196

197
```typescript
198
import { MDCRipple } from "@material/ripple";
199

200
// HTML: <div class="mdc-checkbox__ripple"></div>
201
const checkboxRipple = document.querySelector('.mdc-checkbox__ripple');
202
const ripple = MDCRipple.attachTo(checkboxRipple, { isUnbounded: true });
203
```
204

205
### Custom Component Integration
206

207
```typescript
208
import { MDCRipple, MDCRippleFoundation } from "@material/ripple";
209

210
class MyInteractiveCard {
211
  constructor(element) {
212
    this.root = element;
213
    this.disabled = false;
214
    this.active = false;
215
    
216
    // Custom activation logic
217
    this.root.addEventListener('keydown', evt => {
218
      if (evt.key === ' ' || evt.key === 'Enter') {
219
        this.active = true;
220
      }
221
    });
222
    
223
    this.root.addEventListener('keyup', evt => {
224
      if (evt.key === ' ' || evt.key === 'Enter') {
225
        this.active = false;
226
      }
227
    });
228
    
229
    // Create ripple with custom adapter
230
    const foundation = new MDCRippleFoundation({
231
      ...MDCRipple.createAdapter(this),
232
      isSurfaceActive: () => this.active
233
    });
234
    
235
    this.ripple = new MDCRipple(this.root, foundation);
236
  }
237
}
238
```
239

240
### Declarative Unbounded Ripples
241

242
```html
243
<!-- Use data attribute for unbounded ripples -->
244
<div class="my-surface" data-mdc-ripple-is-unbounded>
245
  <p>Surface with unbounded ripple</p>
246
</div>
247
```
248

249
```typescript
250
import { MDCRipple } from "@material/ripple";
251

252
// Ripple automatically detects data-mdc-ripple-is-unbounded
253
const ripple = new MDCRipple(document.querySelector('.my-surface'));
254
console.log(ripple.unbounded); // true
255
```