0
# DOM Ponyfills
1

2
Cross-browser DOM utilities that provide consistent functionality without modifying global prototypes. A "ponyfill" is a polyfill that doesn't modify the global prototype chain, making it safer for libraries.
3

4
## Capabilities
5

6
### Element Matching
7

8
Check if an element matches a CSS selector with cross-browser compatibility.
9

10
```typescript { .api }
11
/**
12
 * Returns true if the given element matches the given CSS selector
13
 * @param element - The element to test
14
 * @param selector - CSS selector string
15
 * @returns Whether the element matches the selector
16
 */
17
function matches(element: Element, selector: string): boolean;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { matches } from '@material/dom/ponyfill';
24

25
const button = document.querySelector('button');
26
if (matches(button, '.active')) {
27
  // Element has 'active' class
28
}
29

30
if (matches(button, '[aria-pressed="true"]')) {
31
  // Button is pressed
32
}
33
```
34

35
### Closest Ancestor
36

37
Find the closest ancestor element (including the element itself) that matches a selector.
38

39
```typescript { .api }
40
/**
41
 * Returns the ancestor of the given element matching the given selector 
42
 * (which may be the element itself if it matches), or null if no matching ancestor is found
43
 * @param element - The element to start searching from
44
 * @param selector - CSS selector string to match
45
 * @returns The matching ancestor element or null
46
 */
47
function closest(element: Element, selector: string): Element | null;
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { closest } from '@material/dom/ponyfill';
54

55
const listItem = document.querySelector('li');
56
const list = closest(listItem, 'ul, ol');
57
if (list) {
58
  // Found parent list element
59
}
60

61
const card = closest(element, '.mdc-card');
62
if (card) {
63
  // Found ancestor with 'mdc-card' class
64
}
65
```
66

67
### Scroll Width Estimation
68

69
Get the true optical width of an element, even when hidden by display: none.
70

71
```typescript { .api }
72
/**
73
 * Returns the true optical width of the element if visible or an estimation if hidden 
74
 * by a parent element with display: none
75
 * @param element - The element whose width to estimate
76
 * @returns The scroll width in pixels
77
 */
78
function estimateScrollWidth(element: Element): number;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { estimateScrollWidth } from '@material/dom/ponyfill';
85

86
// Get width even if element is hidden
87
const hiddenElement = document.querySelector('.hidden-content');
88
const width = estimateScrollWidth(hiddenElement);
89

90
// Useful for measuring text width before showing
91
const textElement = document.createElement('span');
92
textElement.textContent = 'Long text content';
93
textElement.style.position = 'absolute';
94
textElement.style.visibility = 'hidden';
95
document.body.appendChild(textElement);
96

97
const textWidth = estimateScrollWidth(textElement);
98
document.body.removeChild(textElement);
99
```
100

101
## Browser Compatibility
102

103
These ponyfill functions provide consistent behavior across:
104

105
- Modern browsers with native support
106
- Older browsers using fallback implementations
107
- Internet Explorer 11 and earlier
108
- Mobile browsers with vendor prefixes
109

110
The functions automatically detect native support and use optimal implementations when available.