Volver a las notas

moveBefore(): mueve nodos del DOM sin reiniciarlos

18 de noviembre de 2026·
domjavascriptwebdevwebcomponents
Demo en vivoAbrir a pantalla completa

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 :focus y :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 un HierarchyRequestError.
  • El segundo argumento es obligatorio. parent.moveBefore(node) lanza un TypeError; pasa null de forma explícita.
  • Si el nodo de referencia no es hijo del padre, obtienes un NotFoundError, igual que con insertBefore().

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.

Fuentes