0
# Material DOM
1

2
Material DOM provides essential DOM manipulation utilities specifically designed for Material Components for the Web ecosystem. It offers commonly-used functions for inspecting, traversing, and manipulating DOM elements, including ponyfill functions for cross-browser compatibility, event handling utilities, focus management, accessibility features, and keyboard event normalization.
3

4
## Package Information
5

6
- **Package Name**: @material/dom
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @material/dom`
10

11
## Core Imports
12

13
```typescript
14
import * as events from '@material/dom/events';
15
import * as focusTrap from '@material/dom/focus-trap';
16
import * as keyboard from '@material/dom/keyboard';
17
import * as ponyfill from '@material/dom/ponyfill';
18
```
19

20
For CommonJS:
21

22
```javascript
23
const events = require('@material/dom/events');
24
const focusTrap = require('@material/dom/focus-trap');
25
const keyboard = require('@material/dom/keyboard');
26
const ponyfill = require('@material/dom/ponyfill');
27
```
28

29
Direct module imports (announce module not exported in main index):
30

31
```typescript
32
import { announce, AnnouncerPriority } from '@material/dom/announce';
33
```
34

35
## Basic Usage
36

37
```typescript
38
import * as ponyfill from '@material/dom/ponyfill';
39
import * as keyboard from '@material/dom/keyboard';
40
import { FocusTrap } from '@material/dom/focus-trap';
41

42
// Cross-browser DOM operations
43
const parentElement = ponyfill.closest(element, '.parent-selector');
44
const isMatch = ponyfill.matches(element, '.active');
45

46
// Keyboard event normalization
47
document.addEventListener('keydown', (event) => {
48
  const normalizedKey = keyboard.normalizeKey(event);
49
  if (keyboard.isNavigationEvent(event)) {
50
    // Handle navigation
51
  }
52
});
53

54
// Focus management for modals
55
const focusTrap = new FocusTrap(modalElement, {
56
  initialFocusEl: firstInput
57
});
58
focusTrap.trapFocus();
59
```
60

61
## Architecture
62

63
Material DOM is built around several key components:
64

65
- **Ponyfill Functions**: Cross-browser DOM utilities that don't modify global prototypes
66
- **Event Utilities**: Passive event listener detection and configuration
67
- **Focus Management**: FocusTrap class for modal components with accessibility support
68
- **Keyboard Normalization**: Cross-browser keyboard event handling with standard key constants
69
- **Accessibility Features**: ARIA-live announcements and screen reader support
70
- **SCSS Utilities**: High-contrast mode and accessibility mixins
71

72
## Capabilities
73

74
### Cross-Browser DOM Utilities
75

76
Ponyfill functions for DOM operations that work consistently across browsers without modifying global prototypes.
77

78
```typescript { .api }
79
function closest(element: Element, selector: string): Element | null;
80
function matches(element: Element, selector: string): boolean;
81
function estimateScrollWidth(element: Element): number;
82
```
83

84
[DOM Ponyfills](./ponyfill.md)
85

86
### Event Handling
87

88
Utilities for detecting and configuring passive event listeners for improved performance.
89

90
```typescript { .api }
91
function applyPassive(globalObj?: Window): boolean | EventListenerOptions;
92
```
93

94
[Event Utilities](./events.md)
95

96
### Focus Management
97

98
FocusTrap class for managing focus within modal components like dialogs and drawers.
99

100
```typescript { .api }
101
class FocusTrap {
102
  constructor(root: HTMLElement, options?: FocusOptions);
103
  trapFocus(): void;
104
  releaseFocus(): void;
105
}
106

107
interface FocusOptions {
108
  initialFocusEl?: HTMLElement;
109
  skipInitialFocus?: boolean;
110
  skipRestoreFocus?: boolean;
111
}
112
```
113

114
[Focus Management](./focus-trap.md)
115

116
### Keyboard Event Utilities
117

118
Cross-browser keyboard event normalization with standard key constants.
119

120
```typescript { .api }
121
const KEY: {
122
  UNKNOWN: 'Unknown';
123
  BACKSPACE: 'Backspace';
124
  ENTER: 'Enter';
125
  SPACEBAR: 'Spacebar';
126
  PAGE_UP: 'PageUp';
127
  PAGE_DOWN: 'PageDown';
128
  END: 'End';
129
  HOME: 'Home';
130
  ARROW_LEFT: 'ArrowLeft';
131
  ARROW_UP: 'ArrowUp';
132
  ARROW_RIGHT: 'ArrowRight';
133
  ARROW_DOWN: 'ArrowDown';
134
  DELETE: 'Delete';
135
  ESCAPE: 'Escape';
136
  TAB: 'Tab';
137
};
138

139
function normalizeKey(evt: KeyboardEvent): string;
140
function isNavigationEvent(evt: KeyboardEvent): boolean;
141
```
142

143
[Keyboard Utilities](./keyboard.md)
144

145
### Accessibility Announcements
146

147
ARIA-live region announcements for screen reader accessibility.
148

149
```typescript { .api }
150
enum AnnouncerPriority {
151
  POLITE = 'polite',
152
  ASSERTIVE = 'assertive'
153
}
154

155
interface AnnouncerMessageOptions {
156
  priority?: AnnouncerPriority;
157
  ownerDocument?: Document;
158
}
159

160
function announce(message: string, options?: AnnouncerMessageOptions): void;
161
```
162

163
[Accessibility Announcements](./announce.md)
164

165
## SCSS Mixins
166

167
Material DOM also provides SCSS mixins for enhanced accessibility and high-contrast mode support:
168

169
```scss
170
@use '@material/dom';
171

172
// Transparent border visible in high-contrast mode
173
@include dom.transparent-border($border-width: 1px, $border-style: solid, $query: feature-targeting.all());
174

175
// Visually hide content (screen readers only)
176
@include dom.visually-hidden($query: feature-targeting.all());
177

178
// Target forced-colors mode
179
@include dom.forced-colors-mode($exclude-ie11: false) {
180
  // High contrast styles
181
}
182

183
// Target IE11 support
184
@include dom.ie11-support {
185
  // IE11 specific styles
186
}
187
```
188

189
**Legacy import (deprecated):**
190

191
```scss
192
@use '@material/dom/mixins';
193

194
// Same mixins available through deprecated path
195
@include mixins.transparent-border();
196
@include mixins.visually-hidden();
197
@include mixins.forced-colors-mode();
198
```