@wordpress/dom

What is @wordpress/dom?

@wordpress/dom is a utility package for manipulating and interacting with the DOM (Document Object Model) in WordPress projects. It provides a set of functions to handle common DOM operations, making it easier to work with elements, attributes, and events in a WordPress environment.

What are @wordpress/dom's main functionalities?

Focus Management

This feature allows developers to manage focus within the DOM, such as focusing the first tabbable element within a container. This is particularly useful for accessibility and ensuring a smooth user experience.

const { focus } = require('@wordpress/dom');

// Example: Focus the first tabbable element within a container
focus.focusTabbable(containerElement);

Element Manipulation

Provides utility functions to manipulate DOM elements, such as removing an element from the DOM. This simplifies common tasks that would otherwise require more verbose native DOM methods.

const { remove } = require('@wordpress/dom');

// Example: Remove an element from the DOM
remove(elementToRemove);

Attribute Management

Allows for easy management of element attributes, such as toggling an attribute's presence or value. This is useful for dynamically updating the DOM based on user interactions or application state.

const { toggleAttribute } = require('@wordpress/dom');

// Example: Toggle an attribute on an element
toggleAttribute(element, 'aria-hidden', true);

Other packages similar to @wordpress/dom

jquery

jQuery is a fast, small, and feature-rich JavaScript library. It makes things like HTML document traversal and manipulation, event handling, and animation much simpler with an easy-to-use API that works across a multitude of browsers. Compared to @wordpress/dom, jQuery is more general-purpose and widely used outside of WordPress-specific projects.

dom-helpers

dom-helpers is a tiny modular DOM library that provides a set of utilities for DOM manipulation. It is similar to @wordpress/dom in that it offers functions for common DOM tasks, but it is not specifically tailored for WordPress environments.

vanilla-js-dom

Vanilla JS DOM is a collection of utility functions for DOM manipulation using vanilla JavaScript. It provides similar functionalities to @wordpress/dom but is designed to be a lightweight alternative without any dependencies, suitable for projects that do not require the full WordPress ecosystem.

README

DOM

DOM utilities module for WordPress.

Installation

Install the module

npm install @wordpress/dom --save

API

# computeCaretRect

Get the rectangle for the selection in a container.

Returns

• ?DOMRect: The rectangle.

# documentHasSelection

Check whether the current document has a selection. This checks for both focus in an input field and general text selection.

Returns

• boolean: True if there is selection, false if not.

# documentHasTextSelection

Check whether the current document has selected text. This applies to ranges of text in the document, and not selection inside and elements.

See: https://developer.mozilla.org/en-US/docs/Web/API/Window/getSelection#Related_objects.

Returns

• boolean: True if there is selection, false if not.

# documentHasUncollapsedSelection

Check whether the current document has any sort of selection. This includes ranges of text across elements and any selection inside and

elements. _Returns_ - `boolean`: Whether there is any sort of "selection" in the document. <a name="focus" href="#focus">#</a> **focus** Object grouping `focusable` and `tabbable` utils under the keys with the same name. <a name="getOffsetParent" href="#getOffsetParent">#</a> **getOffsetParent** Returns the closest positioned element, or null under any of the conditions of the offsetParent specification. Unlike offsetParent, this function is not limited to HTMLElement and accepts any Node (e.g. Node.TEXT_NODE). _Related_ - <https://drafts.csswg.org/cssom-view/#dom-htmlelement-offsetparent> _Parameters_ - _node_ `Node`: Node from which to find offset parent. _Returns_ - `?Node`: Offset parent. <a name="getPhrasingContentSchema" href="#getPhrasingContentSchema">#</a> **getPhrasingContentSchema** Get schema of possible paths for phrasing content. _Related_ - <https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content> _Parameters_ - _context_ `string`: Set to "paste" to exclude invisible elements and sensitive data. _Returns_ - `Object`: Schema. <a name="getRectangleFromRange" href="#getRectangleFromRange">#</a> **getRectangleFromRange** Get the rectangle of a given Range. _Parameters_ - _range_ `Range`: The range. _Returns_ - `DOMRect`: The rectangle. <a name="getScrollContainer" href="#getScrollContainer">#</a> **getScrollContainer** Given a DOM node, finds the closest scrollable container node. _Parameters_ - _node_ `Element`: Node from which to start. _Returns_ - `?Element`: Scrollable container node, if found. <a name="insertAfter" href="#insertAfter">#</a> **insertAfter** Given two DOM nodes, inserts the former in the DOM as the next sibling of the latter. _Parameters_ - _newNode_ `Element`: Node to be inserted. - _referenceNode_ `Element`: Node after which to perform the insertion. _Returns_ - `void`: <a name="isEmpty" href="#isEmpty">#</a> **isEmpty** Recursively checks if an element is empty. An element is not empty if it contains text or contains elements with attributes such as images. _Parameters_ - _element_ `Element`: The element to check. _Returns_ - `boolean`: Wether or not the element is empty. <a name="isEntirelySelected" href="#isEntirelySelected">#</a> **isEntirelySelected** Check whether the contents of the element have been entirely selected. Returns true if there is no possibility of selection. _Parameters_ - _element_ `Element`: The element to check. _Returns_ - `boolean`: True if entirely selected, false if not. <a name="isHorizontalEdge" href="#isHorizontalEdge">#</a> **isHorizontalEdge** Check whether the selection is horizontally at the edge of the container. _Parameters_ - _container_ `Element`: Focusable element. - _isReverse_ `boolean`: Set to true to check left, false for right. _Returns_ - `boolean`: True if at the horizontal edge, false if not. <a name="isNumberInput" href="#isNumberInput">#</a> **isNumberInput** Check whether the given element is an input field of type number and has a valueAsNumber _Parameters_ - _element_ `HTMLElement`: The HTML element. _Returns_ - `boolean`: True if the element is input and holds a number. <a name="isPhrasingContent" href="#isPhrasingContent">#</a> **isPhrasingContent** Find out whether or not the given node is phrasing content. _Related_ - <https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content> _Parameters_ - _node_ `Element`: The node to test. _Returns_ - `boolean`: True if phrasing content, false if not. <a name="isTextContent" href="#isTextContent">#</a> **isTextContent** Undocumented declaration. <a name="isTextField" href="#isTextField">#</a> **isTextField** Check whether the given element is a text field, where text field is defined by the ability to select within the input, or that it is contenteditable. See: <https://html.spec.whatwg.org/#textFieldSelection> _Parameters_ - _element_ `HTMLElement`: The HTML element. _Returns_ - `boolean`: True if the element is an text field, false if not. <a name="isVerticalEdge" href="#isVerticalEdge">#</a> **isVerticalEdge** Check whether the selection is vertically at the edge of the container. _Parameters_ - _container_ `Element`: Focusable element. - _isReverse_ `boolean`: Set to true to check top, false for bottom. _Returns_ - `boolean`: True if at the vertical edge, false if not. <a name="placeCaretAtHorizontalEdge" href="#placeCaretAtHorizontalEdge">#</a> **placeCaretAtHorizontalEdge** Places the caret at start or end of a given element. _Parameters_ - _container_ `Element`: Focusable element. - _isReverse_ `boolean`: True for end, false for start. <a name="placeCaretAtVerticalEdge" href="#placeCaretAtVerticalEdge">#</a> **placeCaretAtVerticalEdge** Places the caret at the top or bottom of a given element. _Parameters_ - _container_ `Element`: Focusable element. - _isReverse_ `boolean`: True for bottom, false for top. - _rect_ `[DOMRect]`: The rectangle to position the caret with. - _mayUseScroll_ `[boolean]`: True to allow scrolling, false to disallow. <a name="remove" href="#remove">#</a> **remove** Given a DOM node, removes it from the DOM. _Parameters_ - _node_ `Element`: Node to be removed. _Returns_ - `void`: <a name="removeInvalidHTML" href="#removeInvalidHTML">#</a> **removeInvalidHTML** Given a schema, unwraps or removes nodes, attributes and classes on HTML. _Parameters_ - _HTML_ `string`: The HTML to clean up. - _schema_ `Object`: Schema for the HTML. - _inline_ `Object`: Whether to clean for inline mode. _Returns_ - `string`: The cleaned up HTML. <a name="replace" href="#replace">#</a> **replace** Given two DOM nodes, replaces the former with the latter in the DOM. _Parameters_ - _processedNode_ `Element`: Node to be removed. - _newNode_ `Element`: Node to be inserted in its place. _Returns_ - `void`: <a name="replaceTag" href="#replaceTag">#</a> **replaceTag** Replaces the given node with a new node with the given tag name. _Parameters_ - _node_ `Element`: The node to replace - _tagName_ `string`: The new tag name. _Returns_ - `Element`: The new node. <a name="unwrap" href="#unwrap">#</a> **unwrap** Unwrap the given node. This means any child nodes are moved to the parent. _Parameters_ - _node_ `Node`: The node to unwrap. _Returns_ - `void`: <a name="wrap" href="#wrap">#</a> **wrap** Wraps the given node with a new node with the given tag name. _Parameters_ - _newNode_ `Element`: The node to insert. - _referenceNode_ `Element`: The node to wrap. <!-- END TOKEN(Autogenerated API docs) --> <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." />