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

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

See Importing the JS component 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, priority?: AnnouncerPriority) => void	Announces the message via an aria-live region with the given priority (defaults to polite)