DOM

The @wordpress/dom package provides a comprehensive set of utilities for working with the DOM in WordPress. It includes functions for selection management, element manipulation, focus handling, and HTML sanitization.

Installation

You can install the package using npm:

npm install @wordpress/dom --save

Selection Utilities

documentHasSelection( doc )

Checks whether the current document has a selection, including focus in input fields, textareas, and general rich-text selection.

Document

required

The document to check.

boolean

True if there is selection, false if not.

import { documentHasSelection } from '@wordpress/dom';

if ( documentHasSelection( document ) ) {
	console.log( 'Document has active selection' );
}

documentHasTextSelection( doc )

Checks whether the current document has selected text. This applies to ranges of text in the document, not selection inside <input> and <textarea> elements.

Document

required

The document to check.

boolean

True if there is text selection, false if not.

documentHasUncollapsedSelection( doc )

Checks whether the current document has any sort of uncollapsed selection, including ranges of text and any selection inside textual inputs.

Document

required

The document to check.

boolean

Whether there is any recognizable text selection in the document.

isEntirelySelected( element )

Checks whether the contents of the element have been entirely selected.

HTMLElement

required

The element to check.

boolean

True if entirely selected, false if not.

isSelectionForward( selection )

Returns true if the given selection object is in the forward direction.

Selection

required

Selection object to check.

boolean

Whether the selection is forward.

Caret Positioning

computeCaretRect( win )

Gets the rectangle for the selection in a container.

Window

required

The window of the selection.

DOMRect | null

The rectangle.

getRectangleFromRange( range )

Gets the rectangle of a given Range. Returns null if no suitable rectangle can be found. Use this instead of Range.getBoundingClientRect(), which is often broken for collapsed ranges.

Range

required

The range.

DOMRect | null

The rectangle.

placeCaretAtHorizontalEdge( container, isReverse )

Places the caret at start or end of a given element.

HTMLElement

required

Focusable element.

boolean

required

True for end, false for start.

import { placeCaretAtHorizontalEdge } from '@wordpress/dom';

// Place caret at the end of the element
placeCaretAtHorizontalEdge( element, true );

placeCaretAtVerticalEdge( container, isReverse, rect )

Places the caret at the top or bottom of a given element.

HTMLElement

required

Focusable element.

boolean

required

True for bottom, false for top.

DOMRect

The rectangle to position the caret with.

Edge Detection

isHorizontalEdge( container, isReverse )

Checks whether the selection is horizontally at the edge of the container.

HTMLElement

required

Focusable element.

boolean

required

Set to true to check left, false for right.

boolean

True if at the horizontal edge, false if not.

isVerticalEdge( container, isReverse )

Checks whether the selection is vertically at the edge of the container.

HTMLElement

required

Focusable element.

boolean

required

Set to true to check top, false for bottom.

boolean

True if at the vertical edge, false if not.

Element Type Detection

isFormElement( element )

Detects if element is a form element.

Element

required

The element to check.

boolean

True if form element, false otherwise.

isTextField( node )

Checks 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.

Node

required

The HTML element.

boolean

True if the element is a text field, false if not.

import { isTextField } from '@wordpress/dom';

if ( isTextField( event.target ) ) {
	console.log( 'User is typing in a text field' );
}

isNumberInput( node )

Checks whether the given element is an input field of type number.

Node

required

The HTML node.

boolean

True if the node is number input.

Content Type Utilities

isPhrasingContent( node )

Finds out whether or not the given node is phrasing content.

Node

required

The node to test.

boolean

True if phrasing content, false if not.

See MDN: Phrasing content for more information.

isTextContent( node )

Checks if a node is text content.

Node

required

The node to check.

boolean

Whether the node is text content.

getPhrasingContentSchema( context )

Gets schema of possible paths for phrasing content.

string

Set to “paste” to exclude invisible elements and sensitive data.

object

Schema object.

Element Manipulation

insertAfter( newNode, referenceNode )

Inserts a node in the DOM as the next sibling of another node.

Node

required

Node to be inserted.

Node

required

Node after which to perform the insertion.

import { insertAfter } from '@wordpress/dom';

const newElement = document.createElement( 'div' );
insertAfter( newElement, referenceElement );

remove( node )

Removes a node from the DOM.

Node

required

Node to be removed.

replace( processedNode, newNode )

Replaces one DOM node with another.

Element

required

Node to be removed.

Element

required

Node to be inserted in its place.

replaceTag( node, tagName )

Replaces a node with a new node with the given tag name.

Element

required

The node to replace.

string

required

The new tag name.

Element

The new node.

wrap( newNode, referenceNode )

Wraps a node with a new node with the given tag name.

Element

required

The node to insert.

Element

required

The node to wrap.

unwrap( node )

Unwraps the given node, moving any child nodes to the parent.

Node

required

The node to unwrap.

import { unwrap } from '@wordpress/dom';

// <div><span>Hello</span></div>
// After unwrap(span):
// <div>Hello</div>
unwrap( spanElement );

isEmpty( element )

Recursively checks if an element is empty. An element is not empty if it contains text or elements with attributes such as images.

Element

required

The element to check.

boolean

Whether or not the element is empty.

Layout Utilities

getOffsetParent( node )

Returns the closest positioned element, or null under any of the conditions of the offsetParent specification. Unlike offsetParent, this function accepts any Node (e.g., Node.TEXT_NODE).

Node

required

Node from which to find offset parent.

Node | null

Offset parent.

getScrollContainer( node, direction )

Finds the closest scrollable container node or the node itself, if scrollable.

Element | null

required

Node from which to start.

string

default:"vertical"

Direction of scrollable container to search for (‘vertical’, ‘horizontal’, ‘all’).

Element | undefined

Scrollable container node, if found.

import { getScrollContainer } from '@wordpress/dom';

const scrollParent = getScrollContainer( element, 'vertical' );
if ( scrollParent ) {
	scrollParent.scrollTop = 0;
}

isRTL( element )

Checks whether the element’s text direction is right-to-left.

Element

required

The element to check.

boolean

True if rtl, false if ltr.

HTML Sanitization

safeHTML( html )

Strips scripts and on* attributes from HTML.

string

required

HTML to sanitize.

string

The sanitized HTML.

import { safeHTML } from '@wordpress/dom';

const unsafe = '<div onclick="alert(1)">Click me</div>';
const safe = safeHTML( unsafe );
// Result: '<div>Click me</div>'

removeInvalidHTML( HTML, schema, inline )

Cleans up HTML by removing or unwrapping nodes, attributes, and classes based on a schema.

string

required

The HTML to clean up.

object

required

Schema for the HTML.

boolean

required

Whether to clean for inline mode.

string

The cleaned up HTML.

File Handling

getFilesFromDataTransfer( dataTransfer )

Gets all files from a DataTransfer object.

DataTransfer

required

DataTransfer object to inspect.

File[]

An array containing all files.

import { getFilesFromDataTransfer } from '@wordpress/dom';

element.addEventListener( 'drop', ( event ) => {
	const files = getFilesFromDataTransfer( event.dataTransfer );
	console.log( `Dropped ${files.length} files` );
} );

Focus Management

focus

Object grouping focusable and tabbable utilities under the keys with the same name.

import { focus } from '@wordpress/dom';

// Find all focusable elements
const focusableElements = focus.focusable.find( container );

// Find all tabbable elements
const tabbableElements = focus.tabbable.find( container );

Focusable elements are elements that can receive focus, while tabbable elements are focusable elements that can be reached using the Tab key.

Complete Example

import { 
	documentHasSelection, 
	placeCaretAtHorizontalEdge 
} from '@wordpress/dom';

function handleKeyDown( event ) {
	const { target, keyCode } = event;
	
	if ( keyCode === 37 ) { // Left arrow
		if ( ! documentHasSelection( document ) ) {
			// Move to previous block
			const previousBlock = getPreviousBlock();
			if ( previousBlock ) {
				placeCaretAtHorizontalEdge( previousBlock, true );
			}
		}
	}
}

import { 
	isTextField,
	wrap,
	unwrap,
	safeHTML 
} from '@wordpress/dom';

// Check if element is a text field
if ( isTextField( element ) ) {
	console.log( 'This is a text input' );
}

// Wrap an element
const wrapper = document.createElement( 'div' );
wrap( wrapper, targetElement );

// Sanitize HTML
const clean = safeHTML( userProvidedHTML );

Version

Current version: 4.40.0

​DOM

​Installation

​Selection Utilities

​documentHasSelection( doc )

​documentHasTextSelection( doc )

​documentHasUncollapsedSelection( doc )

​isEntirelySelected( element )

​isSelectionForward( selection )

​Caret Positioning

​computeCaretRect( win )

​getRectangleFromRange( range )

​placeCaretAtHorizontalEdge( container, isReverse )

​placeCaretAtVerticalEdge( container, isReverse, rect )

​Edge Detection

​isHorizontalEdge( container, isReverse )

​isVerticalEdge( container, isReverse )

​Element Type Detection

​isFormElement( element )

​isTextField( node )

​isNumberInput( node )

​Content Type Utilities

​isPhrasingContent( node )

​isTextContent( node )

​getPhrasingContentSchema( context )

​Element Manipulation

​insertAfter( newNode, referenceNode )

​remove( node )

​replace( processedNode, newNode )

​replaceTag( node, tagName )

​wrap( newNode, referenceNode )

​unwrap( node )

​isEmpty( element )

​Layout Utilities

​getOffsetParent( node )

​getScrollContainer( node, direction )

​isRTL( element )

​HTML Sanitization

​safeHTML( html )

​removeInvalidHTML( HTML, schema, inline )

​File Handling

​getFilesFromDataTransfer( dataTransfer )

​Focus Management

​focus

​Complete Example

​Version

​Links

DOM

Installation

Selection Utilities

documentHasSelection( doc )

documentHasTextSelection( doc )

documentHasUncollapsedSelection( doc )

isEntirelySelected( element )

isSelectionForward( selection )

Caret Positioning

computeCaretRect( win )

getRectangleFromRange( range )

placeCaretAtHorizontalEdge( container, isReverse )

placeCaretAtVerticalEdge( container, isReverse, rect )

Edge Detection

isHorizontalEdge( container, isReverse )

isVerticalEdge( container, isReverse )

Element Type Detection

isFormElement( element )

isTextField( node )

isNumberInput( node )

Content Type Utilities

isPhrasingContent( node )

isTextContent( node )

getPhrasingContentSchema( context )

Element Manipulation

insertAfter( newNode, referenceNode )

remove( node )

replace( processedNode, newNode )

replaceTag( node, tagName )

wrap( newNode, referenceNode )

unwrap( node )

isEmpty( element )

Layout Utilities

getOffsetParent( node )

getScrollContainer( node, direction )

isRTL( element )

HTML Sanitization

safeHTML( html )

removeInvalidHTML( HTML, schema, inline )

File Handling

getFilesFromDataTransfer( dataTransfer )

Focus Management

focus

Complete Example

Version

Links