Mover un elemento por el DOM siempre ha sido una pequeña mentira: en realidad el navegador lo quita y lo vuelve a poner, y todo lo que vive dentro empieza de cero. Element.moveBefore() es el primer "mover" de verdad del DOM, y ya funciona en Chrome y Firefox.
Prueba la demo de arriba antes de seguir. La tarjeta tiene tres cosas que odian que las muevan: un <iframe> con su propio reloj, una animación CSS que llena una barra y un campo de texto. Activa el movimiento automático, escribe en el campo y alterna entre moveBefore() e insertBefore(). Con el primero, el reloj sigue contando, la barra sigue llenándose y el cursor se queda donde estaba. Con el segundo, el iframe se recarga, la animación vuelve a cero y pierdes el foco.
Por qué mover reiniciaba todo
appendChild(), insertBefore(), prepend() y compañía no tienen un modo "mover". Si el nodo ya está en el documento, el navegador primero lo saca y luego lo mete en el sitio nuevo. Con un <div> con texto ni lo notas. Con cualquier cosa que tenga estado, esa retirada lo destruye. Según MDN, moveBefore() conserva, entre otras cosas:
- el estado de animaciones y transiciones,
- el estado de carga de un
<iframe>, - estados de interacción como
:focusy:active, - el elemento a pantalla completa,
- los popovers abiertos,
- los
<dialog>modales (no se cierran).
El anuncio de Chrome lo dice sin rodeos: quienes mantienen frameworks dedican mucho esfuerzo a rodear el problema (librerías que transforman el DOM, informes de errores que no pueden arreglar), y aun así los usuarios ven cómo el estado de la aplicación se reinicia cuando no lo esperan.
Cómo funciona
Los mismos argumentos que insertBefore(): el nodo que quieres mover y el nodo delante del que lo colocas, o null para ponerlo al final. Esta es la línea que ejecuta la demo en cada movimiento:
// target es el otro hueco; null significa "al final"
if (mode() === 'move' && supported) target.moveBefore(widget, null);
else target.insertBefore(widget, null);
Devuelve undefined y existe en Element, Document y DocumentFragment. Conviene conocer unas reglas, porque, a diferencia de insertBefore(), lanza errores en casos que quizá no esperas:
- El nodo y el nuevo padre tienen que estar en el mismo documento, y los dos conectados o los dos desconectados. Mover con
moveBefore()un elemento recién creado (que aún no está en la página) a la página lanza unHierarchyRequestError. - El segundo argumento es obligatorio.
parent.moveBefore(node)lanza unTypeError; pasanullde forma explícita. - Si el nodo de referencia no es hijo del padre, obtienes un
NotFoundError, igual que coninsertBefore().
Por eso, y porque Safari todavía no lo tiene, yo lo envolvería en una función pequeña que vuelva al comportamiento de siempre:
function moveNode(parent, node, ref = null) {
if ('moveBefore' in parent) {
try {
parent.moveBefore(node, ref);
return;
} catch {
// No se puede mover (p. ej., un nodo que aún no está en la página): seguimos.
}
}
parent.insertBefore(node, ref);
}
La he ejecutado en Chromium, Firefox y WebKit con Playwright: en los dos primeros, un campo con el foco lo conserva tras moverlo; en WebKit recurre a insertBefore() y pierde el foco, como era de esperar. Un nodo que aún no está en la página pasa por el catch y se inserta de la forma normal.
Custom elements: connectedMoveCallback()
Aquí hay una trampa para los web components. Mover con insertBefore() dispara disconnectedCallback() y después connectedCallback(), y como ahí es donde la mayoría de componentes se inicializan y se limpian, un simple movimiento puede borrarles el estado. La guía de custom elements de MDN aclara que moveBefore() por sí solo no lo arregla: además tienes que definir connectedMoveCallback(). Si existe y mueves el elemento con moveBefore(), se ejecuta en lugar de los otros dos.
class MovableWidget extends HTMLElement {
connectedCallback() { console.log('connected'); }
disconnectedCallback() { console.log('disconnected'); }
connectedMoveCallback() { console.log('moved'); }
}
customElements.define('movable-widget', MovableWidget);
En mi prueba, mover el elemento con moveBefore() solo registró moved; devolverlo con insertBefore() registró disconnected y connected. Si lo único que quieres es saltarte la limpieza, basta con un connectedMoveCallback() vacío.
Soporte en navegadores y trampas
Según los datos de compatibilidad de MDN, moveBefore() llegó en Chrome 133 (febrero de 2025) y en Firefox 144 (octubre de 2025). Safari no lo soporta: el bug de seguimiento de WebKit sigue abierto, con algunas dependencias pendientes. Así que no es Baseline y la detección de soporte es obligatoria:
const supported = 'moveBefore' in Element.prototype;
Otras cosas que conviene tener en cuenta:
- MutationObserver sigue viendo una retirada y una inserción. Lo dice MDN y mi prueba lo confirmó: un movimiento generó un registro con un nodo eliminado y otro con un nodo añadido. Si tu código reacciona a "nodo eliminado" limpiando cosas, comprueba si ha vuelto.
- Es "la mayor parte" del estado, no todo. El artículo de Chrome dice con cuidado que conserva la mayor parte del estado. Prueba justo lo que te importa.
- El plan B se nota. En Safari, el usuario verá el reinicio de siempre. Para mejora progresiva está bien, pero no construyas algo que solo tenga sentido si el iframe nunca se recarga.
Qué vigilar
- Safari. El bug 281223 de WebKit es el que hay que seguir; cuando se cierre,
moveBefore()podrá aspirar a Baseline. - Frameworks y librerías. Cualquier cosa que reordene listas con claves o transforme HTML podría usar
moveBefore()donde exista y dejar de recargar embeds y de perder el foco sin coste. - Tus propios componentes. Si escribes custom elements, añadir
connectedMoveCallback()no cuesta nada y hace que se porten bien hoy en Chrome y Firefox.