CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-material--dom

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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();
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@material/dom@14.0.x
Publish Source
CLI
Badge
tessl/npm-material--dom badge