@material/dom
Advanced tools
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.
npm install @material/dom
import * as ponyfill from '@material/dom/ponyfill';
See Importing the JS component for more information on how to import JavaScript.
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;. |
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 |
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. |
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) |
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). |
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). |
6.0.0 (2020-04-22)
[@use](https://github.com/use) (098ae32)indeterminate checkbox (b273afa)select: HTML Markup significantly changed, see README; REMOVED adapter methods isSelectedTextFocused, getSelectedTextAttr, setSelectedTextAttr; ADDED adapter methods isSelectAnchorFocused, getSelectAnchorAttr, setSelectAnchorAttr; removed variables outlined-dense-label-position-y, icon-padding; added variables minimum-height-for-filled-label, filled-baseline-top, selected-text-height, anchor-padding-left, anchor-padding-left-with-leading-icon, anchor-padding-right.
text-field: Redundant mixins mdc-text-field-textarea-fill-color, mdc-text-field-textarea-stroke-color, mdc-text-field-fullwidth-bottom-line-color removed. Instead, use mdc-text-field-fill-color, mdc-text-field-outline-color, and mdc-text-field-bottom-line-color respectively to achieve the same effect.
textfield: mdc-text-field--dense and associated mixins/variables have been removed. Use the density() mixin instead.
textfield: removed the following variables: $input-padding, $input-padding-top, $input-padding-bottom, $outlined-input-padding-top, $outlined-input-padding-bottom, $input-border-bottom
linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.
linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.
typography: typography.baseline-top() and typography.baseline-bottom() are now private. Use typography.baseline() for containers and typography.text-baseline() for text with $top and $bottom params.
chips: The touch target and text now appear inside the primary action element. Please see the readme for markup changes.
textfield: filled text fields must include a <div class="mdc-text-field__ripple"></div>
textfield: Filled textfields will no longer show a floating label at certain densities. This can be overridden by setting $mdc-text-field-minimum-height-for-filled-label: 40px
chips: Both MDCChipAdapter and MDCChipSetAdapter have new methods. MDCChipSetFoundation event handlers now accept the corresponding chip event detail interface as the sole argument. The root property has been removed from the MDCChipRemovalEventDetail interface.
line-ripple: mdc-line-ripple-color() mixin has been renamed to mdc-line-ripple-active-color()
textfield: Default textfields must now specify mdc-text-field--filled. Disabled outlined textfields no longer have a shaded background. Height mixin no longer specifies a baseline override, use typography's baseline-top mixin.
Four variables and a mixin in mdc-textfield were renamed to use a mdc-text-field- prefix when depended on via @import (formerly mdc-required-text-field-label-asterisk_, now required-label-asterisk_).
textfield: icons must use .mdc-text-field__icon--leading or .mdc-text-field__icon--trailing classes. mdc-text-field-icon-color() mixin has been split into mdc-text-field-leading-icon-color() and mdc-text-field-trailing-icon-color().
switch: Added setNativeControlAttr method in mdc-switch adapter.
checkbox: remove event listener for 'change' and add event listener for 'click'.
$mdc-button-disabled-container-fill-color
renamed to $mdc-button-disabled-container-color.$edgeOptOut option from mdc-theme-prop() Sass mixin.FAQs
DOM manipulation utilities for Material Components for the web
We found that @material/dom demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.