moveBefore() DOM API

Introduction

Chrome 133 was officially released on February 4, 2025, bringing an eagerly anticipated new feature: the moveBefore() DOM API. This new API gives developers a more elegant way to move elements within the DOM while avoiding the frustrating state loss caused by traditional approaches. Let us see how it works and what it can change in your projects.

The Pain Points of Moving DOM Elements

You may frequently use appendChild() or insertBefore() to manipulate the DOM. But have you noticed that when you try to “move” an existing element, it is actually removed and then inserted again behind the scenes? This behavior originated in the design of the first DOM standard in 1998 and has remained unchanged ever since.

For simple elements such as <p>, this “remove and insert” process usually causes no problems. But complex nodes may include:

• <iframe> elements with video playback state
• Fullscreen elements
• CSS animations
• User input fields with focus state

The implicit removal resets their state, degrading the user experience and forcing developers to write complicated workarounds, use libraries such as MorphDOM, or face bug reports with no practical solution.

Try moving an element with a CSS animation or an <iframe> within the DOM tree. You will find that the animation restarts, the video pauses, or focus is lost. These side effects are a constant source of frustration.

moveBefore(): A True “Move” Operation

To solve this problem, the Chrome team introduced the new moveBefore() API. It accepts the same parameters as insertBefore(), but with one crucial difference: it performs an atomic move. In other words, the target node moves directly to its new position without going through a “remove and reinsert” process, allowing most of its state to be preserved.

This new API enables developers to:

• Preserve video playback state: Whether using <video> or <iframe>, playback is not interrupted while the user browses.
• Keep focus intact: When an input field moves, the user’s cursor position remains unchanged.
• Maintain seamless animations: Animations continue running as content is added or removed.
• Improve morphing algorithm efficiency: Existing DOM nodes can be reconciled with new content more precisely.
• Support dynamic UIs: Modals, popups, and fullscreen elements can move without losing state.

Code Example

The following simple example shows how to use moveBefore() to move an animated element from one container to another while preserving its animation state:

In this example, clicking the “Move with moveBefore” button moves the element from Container 1 to Container 2 while preserving its animation state. Clicking the “Move with insertBefore” button first removes the element from Container 1 and then inserts it into Container 2, causing the animation to restart.

How Can You Try It?

Want to try this new feature? There are two ways:

1. Experimental trial: Enable the chrome://flags/#atomic-move flag in Chrome, then visit the official demo website.
2. Regular use: Once Chrome 133 was released on February 4, 2025, the API became available to call directly in projects.

The Chrome team is also working to bring moveBefore() to other browsers, filling a long-standing gap in the Web platform.

Why Does This Matter?

For JavaScript developers, moveBefore() is more than just a new tool: it expands the design space for dynamic user experiences. Whether you are building smooth animations, stable video playback, or complex interactive components, this API makes the work simpler and more reliable.

Reference: Official Chrome announcement (February 2025)