or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

announce.mdevents.mdfocus-trap.mdindex.mdkeyboard.mdponyfill.md
tile.json

tessl/npm-material--dom

DOM manipulation utilities for Material Components providing cross-browser compatibility, focus management, and accessibility features.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@material/dom@14.0.x

To install, run

npx @tessl/cli install tessl/npm-material--dom@14.0.0

index.mddocs/

Material DOM

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.

Package Information

  • Package Name: @material/dom
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @material/dom

Core Imports

import * as events from '@material/dom/events';
import * as focusTrap from '@material/dom/focus-trap';
import * as keyboard from '@material/dom/keyboard';
import * as ponyfill from '@material/dom/ponyfill';

For CommonJS:

const events = require('@material/dom/events');
const focusTrap = require('@material/dom/focus-trap');
const keyboard = require('@material/dom/keyboard');
const ponyfill = require('@material/dom/ponyfill');

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

import { announce, AnnouncerPriority } from '@material/dom/announce';

Basic Usage

import * as ponyfill from '@material/dom/ponyfill';
import * as keyboard from '@material/dom/keyboard';
import { FocusTrap } from '@material/dom/focus-trap';

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

// Keyboard event normalization
document.addEventListener('keydown', (event) => {
  const normalizedKey = keyboard.normalizeKey(event);
  if (keyboard.isNavigationEvent(event)) {
    // Handle navigation
  }
});

// Focus management for modals
const focusTrap = new FocusTrap(modalElement, {
  initialFocusEl: firstInput
});
focusTrap.trapFocus();

Architecture

Material DOM is built around several key components:

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

Capabilities

Cross-Browser DOM Utilities

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

function closest(element: Element, selector: string): Element | null;
function matches(element: Element, selector: string): boolean;
function estimateScrollWidth(element: Element): number;

DOM Ponyfills

Event Handling

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

function applyPassive(globalObj?: Window): boolean | EventListenerOptions;

Event Utilities

Focus Management

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

class FocusTrap {
  constructor(root: HTMLElement, options?: FocusOptions);
  trapFocus(): void;
  releaseFocus(): void;
}

interface FocusOptions {
  initialFocusEl?: HTMLElement;
  skipInitialFocus?: boolean;
  skipRestoreFocus?: boolean;
}

Focus Management

Keyboard Event Utilities

Cross-browser keyboard event normalization with standard key constants.

const KEY: {
  UNKNOWN: 'Unknown';
  BACKSPACE: 'Backspace';
  ENTER: 'Enter';
  SPACEBAR: 'Spacebar';
  PAGE_UP: 'PageUp';
  PAGE_DOWN: 'PageDown';
  END: 'End';
  HOME: 'Home';
  ARROW_LEFT: 'ArrowLeft';
  ARROW_UP: 'ArrowUp';
  ARROW_RIGHT: 'ArrowRight';
  ARROW_DOWN: 'ArrowDown';
  DELETE: 'Delete';
  ESCAPE: 'Escape';
  TAB: 'Tab';
};

function normalizeKey(evt: KeyboardEvent): string;
function isNavigationEvent(evt: KeyboardEvent): boolean;

Keyboard Utilities

Accessibility Announcements

ARIA-live region announcements for screen reader accessibility.

enum AnnouncerPriority {
  POLITE = 'polite',
  ASSERTIVE = 'assertive'
}

interface AnnouncerMessageOptions {
  priority?: AnnouncerPriority;
  ownerDocument?: Document;
}

function announce(message: string, options?: AnnouncerMessageOptions): void;

Accessibility Announcements

SCSS Mixins

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

@use '@material/dom';

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

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

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

// Target IE11 support
@include dom.ie11-support {
  // IE11 specific styles
}

Legacy import (deprecated):

@use '@material/dom/mixins';

// Same mixins available through deprecated path
@include mixins.transparent-border();
@include mixins.visually-hidden();
@include mixins.forced-colors-mode();