# @material/dom

> DOM manipulation utilities for Material Components for the web

Latest version **14.0.0** (published 2022-04-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install @material/dom
pnpm add @material/dom
yarn add @material/dom
bun add @material/dom
```

## Health

**Score 28/100 (F)** — status: abandoned.

Positive: has types package; esm support; no vulnerabilities; popular repo.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 14.0.0 |
| Published | 2022-04-28 |
| First published | 2018-09-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/material__dom) |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 110.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17051 |
| Maintainers | yefim, abhiomkar, azakus, bicknellr, material-admin, aprigogin, patrickrodee, aomarks, emarquez, allanchen, esgonzalez, asyncliz, candysonya, ssuarez, taylorv |

## Links

- npm: https://www.npmjs.com/package/@material/dom
- Repository: https://github.com/material-components/material-components-web
- Homepage: https://github.com/material-components/material-components-web#readme
- Issues: https://github.com/material-components/material-components-web/issues
- npm.io page: https://npm.io/package/@material/dom

## Dependencies (2)

- [tslib](https://npm.io/package/tslib.md) ^2.1.0
- [@material/feature-targeting](https://npm.io/package/@material/feature-targeting.md) ^14.0.0

## Recent versions

- 14.0.0 (latest) — 2022-04-28
- 15.0.0-canary.423edc3dc.0 (canary) — 2024-06-26
- 12.0.0-nightly.778a0e8a.0 (nightly) — 2021-07-20
- 4.0.0-alpha.0 (next) — 2019-08-07
- 15.0.0-canary.cfec83c74.0 — 2024-05-20
- 15.0.0-canary.2f5b899bc.0 — 2024-05-20
- 15.0.0-canary.f80ac92b0.0 — 2024-05-02
- 15.0.0-canary.4b35cb7d0.0 — 2024-05-02
- 15.0.0-canary.65c10a622.0 — 2024-04-25
- 15.0.0-canary.311f29a60.0 — 2024-04-23
- 15.0.0-canary.5bebc0064.0 — 2024-04-11
- 15.0.0-canary.68edc03c6.0 — 2024-04-08
- 15.0.0-canary.453a6248a.0 — 2024-03-25
- 15.0.0-canary.819498d8c.0 — 2024-03-15
- 15.0.0-canary.c43b3438b.0 — 2024-02-23
- … 1637 more at https://npm.io/package/@material/dom/versions

## README

<!--docs:
title: "DOM"
layout: detail
section: components
excerpt: "Provides commonly-used utilities for inspecting, traversing, and manipulating the DOM."
path: /catalog/dom/
-->

# DOM

MDC DOM provides commonly-used utilities for inspecting, traversing, and manipulating the DOM.

Most of the time, you shouldn't need to depend on `mdc-dom` directly. It is useful however if you'd like to write custom components that follow MDC Web's pattern and elegantly integrate with the MDC Web ecosystem.

## Installation

```
npm install @material/dom
```

## Basic Usage

```js
import * as ponyfill from '@material/dom/ponyfill';
```

> See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.

## Ponyfill Functions

The `ponyfill` module provides the following functions:

Function Signature | Description
--- | ---
`closest(element: Element, selector: string) => ?Element` | Returns the ancestor of the given element matching the given selector (which may be the element itself if it matches), or `null` if no matching ancestor is found.
`matches(element: Element, selector: string) => boolean` | Returns true if the given element matches the given CSS selector.
`estimateScrollWidth(element: Element) => number`  | Returns the true optical width of the element if visible or an estimation if hidden by a parent element with `display: none;`.

## Event Functions

External frameworks and libraries can use the following event utility methods.

Method Signature | Description
--- | ---
`util.applyPassive(globalObj = window) => object` | Determine whether the current browser supports passive event listeners

## Focus Trap

The `FocusTrap` utility traps focus within a given element. It is intended for usage from MDC-internal
components like dialog and modal drawer.

Method Signature | Description
--- | ---
`trapFocus() => void` | Traps focus in the root element. Also focuses on `initialFocusEl` if set; otherwise, sets initial focus to the first focusable child element.
`releaseFocus() => void` | Releases focus from the root element. Also restores focus to the previously focused element.

## Announce

The `announce` utility file contains a single helper method for announcing a message via an `aria-live` region. It is intended for usage from MDC-internal components.

Method Signature | Description
--- | ---
`announce(message: string, options?: AnnouncerMessageOptions) => void` | Announces the message via an `aria-live` region with the given options. `AnnouncerMessageOptions.priority` defaults to polite and `AnnouncerMessageOptions.ownerDocument` defaults to the global document.
<!-- TODO(b/148462294): Remove once only exported members are required in docs `say()` --> <!-- | --> <!-- DO NOT USE -->

## Keyboard

The `keyboard` utility provides helper methods for normalizing `KeyboardEvent` keys across browsers. It is intended for usage from MDC-internal components.

Method Signature | Description
--- | ---
`normalizeKey(evt: KeyboardEvent) => string` | Returns a normalized string derived from `KeyboardEvent`'s `keyCode` property to be standard across browsers.
`isNavigationEvent(evt: KeyboardEvent) => boolean` | Returns `true` if the event is a navigation event (Page Up, Page Down, Home, End, Left, Up, Right, Down).

## Mixins

The module provides a single SASS mixin which helps improves a DOM element's UX for high-contrast mode users.

Mixin | Description
--- | ---
`transparent-border` | Emits necessary layout styles to set a transparent border around an element without interfering with the rest of its component layout. The border is only visible in high-contrast mode. The target element should be a child of a relatively positioned top-level element (i.e. a ::before pseudo-element).

---
_Source: https://npm.io/package/@material/dom · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._