Mover nodos del DOM sin perder su estado
Vea cómo Element.moveBefore() conserva el estado de iframes, foco, animaciones y diálogos al mover nodos DOM, con sintaxis, límites y alternativas.
Element.moveBefore() mueve un nodo que ya está en el documento sin el paso de eliminar e insertar de nuevo que realizan appendChild() e insertBefore(). Así, un <iframe> conserva la página cargada, un input con el foco lo mantiene y una animación CSS en curso sigue ejecutándose.
La mayoría de los desarrolladores que cambian de nodo padre elementos ya renderizados se ha topado con esto: arrastras una tarjeta a otra columna y el reproductor incrustado en ella se queda en blanco y se recarga, o el campo en el que escribías pierde el foco a mitad de una palabra.
Chrome incorporó moveBefore() en Chrome 133, y la funcionalidad aparece en las notas de la versión de Chrome 133 como “DOM state-preserving move”. Este artículo cubre la sintaxis, una demo, la lista exacta de estados que se conservan, los casos de error, los hooks de los custom elements y un fallback seguro. Si antes necesitas repasar los fundamentos, consulta cómo trabajar con el DOM en JavaScript y el ciclo de vida de los elementos del DOM.
Puntos clave
parent.moveBefore(node, ref)recibe los mismos argumentos queinsertBefore(), pero mueve el nodo sin eliminarlo y volver a insertarlo, de modo que los iframes, el foco, las animaciones, los popovers y los diálogos modales conservan su estado.- El nodo que se mueve debe ser un nodo Element o CharacterData. Los movimientos entre documentos, entre árboles conectados y desconectados, o hacia un descendiente del propio nodo lanzan
HierarchyRequestError. - Un
MutationObserversigue viendo un movimiento conmoveBefore()como una eliminación y una adición. - Los custom elements que definen
connectedMoveCallback()reciben ese callback en lugar dedisconnectedCallback()yconnectedCallback(). - Safari no admite
moveBefore(), así que comprueba'moveBefore' in Element.prototypey recurre ainsertBefore()como fallback.
¿Por qué appendChild e insertBefore restablecen el estado?
Cada movimiento realizado con appendChild() o insertBefore() consiste en realidad en dos operaciones: el navegador elimina el nodo del documento y después lo vuelve a insertar. El artículo de lanzamiento del equipo de Chrome señala que, desde sus primeros estándares, el DOM no ha tenido otra forma de mover un nodo. Al eliminar un nodo se destruye el estado que solo existe mientras el nodo está conectado. Un iframe descarga y vuelve a cargar su documento, un elemento con el foco lo pierde, las animaciones CSS vuelven a empezar y los popovers y diálogos modales abiertos se cierran.
En las grabaciones de sesión (session replays) de dashboards con elementos reordenables, el bug suele verse así: el usuario arrastra una tarjeta, sigue escribiendo y las pulsaciones de teclado no llegan a ningún sitio porque el campo ha perdido el foco. Los iframes incrustados se recargan visiblemente en mitad de la sesión.
Sintaxis de moveBefore()
moveBefore() recibe los mismos dos argumentos que insertBefore(): el nodo que se va a mover y un nodo de referencia. Si se pasa null como referencia, el nodo se mueve al final de los hijos del padre.
parent.moveBefore(movedNode, referenceNode);
parent.moveBefore(movedNode, null); // append
Según la referencia de moveBefore() en MDN, el nodo que se mueve debe ser un nodo Element o CharacterData. Los nodos de texto están permitidos, pero, por ejemplo, los document types no. El método también existe en Document y en DocumentFragment, por lo que se pueden mover nodos dentro de un fragmento aunque un fragmento nunca esté conectado al documento. El método está definido en el DOM Living Standard.
Demo: mover un iframe con y sin moveBefore
La forma más rápida de ver la diferencia es con un iframe que tenga su propio estado interno. Esta demo usa srcdoc, así que no realiza ninguna petición de red.
<div id="left" class="box">
<iframe id="frame" srcdoc="<button onclick='this.textContent=++n'>0</button><script>let n=0</script>"></iframe>
</div>
<div id="right" class="box"></div>
<button id="viaInsert">Move with insertBefore()</button>
<button id="viaMove">Move with moveBefore()</button>
<script>
const frame = document.getElementById('frame');
const left = document.getElementById('left');
const right = document.getElementById('right');
const target = () => (frame.parentElement === left ? right : left);
document.getElementById('viaInsert').onclick = () =>
target().insertBefore(frame, null); // iframe reloads, counter back to 0
document.getElementById('viaMove').onclick = () =>
target().moveBefore(frame, null); // counter value survives
</script>
Haz clic varias veces en el contador dentro del frame y después prueba cada botón. insertBefore() recarga el frame y el contador vuelve a cero. moveBefore() conserva la cuenta. El segundo botón solo funciona en un navegador que admita el método (consulta la sección de detección de funcionalidades más abajo).
El foco se comporta de la misma manera:
const input = document.querySelector('#note');
input.focus();
sidebar.moveBefore(input, null);
console.log(document.activeElement === input); // true
// With sidebar.insertBefore(input, null), focus is lost
¿Qué estado conserva moveBefore()?
moveBefore() conserva un conjunto concreto de estados, enumerados en MDN. No conserva todos los estados posibles:
- Estado de animaciones y transiciones
- Estado de carga de
<iframe> :focusy:active- Estado de elemento en pantalla completa
- Estado abierto de los popovers
- Estado de
<dialog>modal
Los elementos nativos <video> y <audio> conservan su estado de reproducción incluso cuando se mueven con appendChild() o insertBefore(). Por tanto, en el caso de los contenidos multimedia, moveBefore() es relevante cuando el reproductor está incrustado en un <iframe>, como ocurre con un vídeo incrustado de terceros, y no con los elementos multimedia nativos.
Errores y restricciones de moveBefore()
moveBefore() es más estricto que insertBefore(). Lanza errores en casos en los que insertBefore() haría silenciosamente una eliminación seguida de una inserción.
| Error | Se produce cuando | Qué hacer |
|---|---|---|
HierarchyRequestError | Se mueve entre un árbol conectado y uno desconectado | Usar insertBefore() |
HierarchyRequestError | Se mueve entre documentos | Usar insertBefore() (o adoptNode() primero) |
HierarchyRequestError | Se mueve un nodo dentro de su propio descendiente | Corregir el destino: es un error de lógica |
HierarchyRequestError | movedNode no es un Element ni CharacterData | Usar insertBefore() |
NotFoundError | referenceNode no es hijo del padre | Pasar un hijo real o null |
TypeError | Falta el segundo argumento | Pasar null explícitamente para añadir al final |
La fila del TypeError pilla desprevenida a mucha gente porque se arrastran los hábitos de insertBefore(): no se puede añadir al final llamando a moveBefore(node) con un solo argumento.
MutationObserver y connectedMoveCallback
Un MutationObserver sigue registrando un nodo movido con moveBefore() como un nodo eliminado y un nodo añadido, por lo que los observers existentes siguen recibiendo registros de los movimientos. Los pasos de movimiento del DOM Standard encolan un registro de eliminación para el padre anterior y un registro de adición para el nuevo. El código que interpreta una eliminación como “destruido” necesita otra señal si debe distinguir los movimientos de los borrados. Para configurar observers, consulta las tres APIs de observers del DOM.
Los custom elements disponen de un hook específico para los movimientos: connectedMoveCallback(). Como explica la guía de custom elements de MDN, cuando connectedMoveCallback() está definido, se invoca en lugar de connectedCallback() y disconnectedCallback() cada vez que el elemento se mueve a otra posición del DOM mediante Element.moveBefore().
class DashCard extends HTMLElement {
connectedCallback() { /* initial setup: subscriptions, timers */ }
disconnectedCallback() { /* teardown */ }
connectedMoveCallback() { /* runs instead of the two above on moveBefore() */ }
}
customElements.define('dash-card', DashCard);
Si la clase no define connectedMoveCallback(), un movimiento con moveBefore() sigue ejecutando disconnectedCallback() y después connectedCallback(). Definir el método, aunque sea como una función vacía, sustituye a ese par. La especificación de HTML describe este comportamiento.
Detección de funcionalidad y fallback para moveBefore
Comprueba 'moveBefore' in Element.prototype antes de llamar al método. Recurre a insertBefore() cuando el método no exista y también cuando lance un HierarchyRequestError en un movimiento que insertBefore() aceptaría. Según caniuse, lo admiten Chrome y Edge 133+ y Firefox 144+, pero no Safari. web-features lo clasifica como “Limited availability” (disponibilidad limitada) y no como Baseline.
function moveNode(parent, node, ref = null) {
if ('moveBefore' in Element.prototype) {
try {
parent.moveBefore(node, ref);
return;
} catch (err) {
if (err.name !== 'HierarchyRequestError') throw err; // NotFoundError etc. are real bugs
}
}
const active = document.activeElement;
parent.insertBefore(node, ref); // state-resetting path
if (active && node.contains(active)) active.focus();
}
El fallback con insertBefore() sigue recargando los iframes, reiniciando las animaciones y cerrando los diálogos, exactamente igual que insertBefore() ha hecho siempre. Restaurar el foco solo devuelve el foco al elemento; la posición del cursor no está garantizada. Esta comprobación solo cubre padres de tipo Element. No indica si Document o DocumentFragment admiten el método.
Conclusión
moveBefore() dota al DOM, por primera vez, de un movimiento real: una sola llamada que mantiene los iframes cargados, el foco en su sitio y las animaciones en marcha, siempre que se respeten las restricciones que enumera MDN. Localiza todas las llamadas a appendChild() o insertBefore() de tu código de drag-and-drop o de morphing que muevan un nodo ya renderizado, haz que pasen por un helper como moveNode() y añade connectedMoveCallback() a cualquier custom element cuya inicialización no deba volver a ejecutarse cuando se reposiciona.
Preguntas frecuentes
¿Puede moveBefore() mover un elemento hacia dentro o hacia fuera de un shadow root?
Sí. ShadowRoot hereda de DocumentFragment, por lo que tiene su propio método moveBefore(). El movimiento debe permanecer dentro del mismo shadow-including root, y un shadow root conectado cumple ese requisito para cualquier nodo conectado al mismo documento. Mover contenido del light DOM a un shadow tree conectado conserva el foco, el estado de carga de los iframes y el resto de estados que enumera MDN.
¿Por qué moveBefore() lanza un error cuando inserto un elemento recién creado?
Un elemento creado con document.createElement() todavía no está conectado al documento. Mover un nodo desconectado a un padre conectado lanza un HierarchyRequestError. Usa appendChild() o insertBefore() para la primera inserción. Un nodo que nunca ha estado conectado no tiene estado de iframe, foco ni animaciones que conservar, así que no se pierde nada. Usa moveBefore() solo para los movimientos posteriores.
¿Se puede crear un polyfill de moveBefore() para Safari?
No. Un polyfill puede añadir un método moveBefore() que llame a insertBefore(), pero eso solo replica el nombre del método. Es el motor del navegador el que mantiene vivos los documentos de los iframes, el foco, las animaciones y los popovers abiertos durante el movimiento, y JavaScript no puede hacerlo. En navegadores sin soporte nativo, un shim se comporta exactamente igual que insertBefore() y restablece el mismo estado.
¿Hay librerías que ya usen moveBefore()?
Sí. htmx añadió soporte para moveBefore() en la versión 2.0.3, publicada en octubre de 2024. Cuando el navegador expone moveBefore(), htmx lo utiliza para mover los elementos marcados con hx-preserve durante los intercambios de contenido, de modo que esos elementos conservan su estado. En navegadores sin el método, htmx vuelve a su comportamiento habitual, que mueve los elementos a la antigua usanza, eliminándolos e insertándolos de nuevo.