Editorial review: Add moveBefore() docs

[chrisdavidmills]

Description

Chrome 133 supports the moveBefore() method; see https://chromestatus.com/feature/5135990159835136.

This PR documents the new method on Document, DocumentFragment, and Element.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (7 pages)

• /en-US/docs/Web/API/Document/moveBefore
• /en-US/docs/Web/API/DocumentFragment/moveBefore
• /en-US/docs/Web/API/DocumentFragment
• /en-US/docs/Web/API/Document
• /en-US/docs/Web/API/Element/moveBefore
• /en-US/docs/Web/API/Element
• /en-US/docs/Web/API/Web_components/Using_custom_elements

Flaws (14)

Note! 4 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Document
Title: Document
Flaw count: 10

• macros:
  • Macro produces link /en-US/docs/Web/SVG/Element/svg which is a redirect
  • Can't resolve /en-US/docs/Web/API/Document/xmlStandalone
  • Can't resolve /en-US/docs/Web/API/Document/captureEvents
  • Can't resolve /en-US/docs/Web/API/Document/getBoxQuads
  • Can't resolve /en-US/docs/Web/API/Document/releaseEvents
  • and 5 more flaws omitted

---

URL: /en-US/docs/Web/API/Element
Title: Element
Flaw count: 1

• macros:
  • Can't resolve /en-US/docs/Web/API/Element/getBoxQuads

---

URL: /en-US/docs/Web/API/Web_components/Using_custom_elements
Title: Using custom elements
Flaw count: 3

• macros:
  • Macro produces link /en-US/docs/Web/Web_Components/Using_custom_elements which is a redirect
  • Macro produces link /en-US/docs/Web/Web_Components/Using_shadow_DOM which is a redirect
  • Macro produces link /en-US/docs/Web/Web_Components/Using_templates_and_slots which is a redirect

(comment last updated: 2025-04-09 13:47:52)

[noamr]

Thanks! A few technical comments:

• What is preserved for <dialog> is its modal state. See https://github.com/web-platform-tests/wpt/blob/e3e6eee31d98d5b5dea1a3159febe139280c10ad/dom/nodes/moveBefore/modal-dialog.html

• Selection is a bit of an odd one; It only preserves selection in certain situations - namely when the anchor node of the selection is the target of the moveBefore.

• This is missing a section about custom elements. By default, a custom elements that get moved using moveBefore, receive their disconnectedCallback and connectedCallback invoked. To have custom support for state-preserving move, an author can add a connectedMoveCallback that would be called instead of connected/disconnected. It can be empty to avoid the disconnection/connection side-effects, or contain logic that responds to a move.

• We should say something about the constraints: moveBefore only works within the same document, and it cannot work as a way to connect or disconnect an element. Moving a disconnected element to a connected parent or vice versa, would result in an exception. Users of this API that want to be resilient to this need to know in advance whether they're acting across disconnected/connected state, across documents, and use insertBefore instead in these cases (or try/catch the moveBefore).

• As far as mutation observers go, there is no particular change, but it might be worthwhile to note that the moved element would appear as removed/re-inserted in mutation observers.

[chrisdavidmills]

Thanks! A few technical comments:

* What is preserved for `<dialog>` is its modal state. See https://github.com/web-platform-tests/wpt/blob/e3e6eee31d98d5b5dea1a3159febe139280c10ad/dom/nodes/moveBefore/modal-dialog.html

Cool, thanks for the tip; I've updated the list of preserved state things to account for this.

Note that, in light of your comments, I've moved this content to a new "Description" section on the page and added the other bits you wanted me to include there.

* Selection is a bit of an odd one; It only preserves selection in certain situations - namely when the anchor node of the selection is the target of the `moveBefore`.

I did a bit of testing on this but couldn't get the selection to preserve. I've just removed the bullet about preserving selection, as this doesn't seem to me to be a case that will come up often or behavior that can be particularly relied upon. What do you think?

* This is missing a section about custom elements. By default, a custom elements that get moved using `moveBefore`, receive their `disconnectedCallback` and `connectedCallback` invoked. To have custom support for state-preserving move, an author can add a `connectedMoveCallback` that would be called instead of connected/disconnected. It can be empty to avoid the disconnection/connection side-effects, or contain logic that responds to a move.

I've added a section to cover this inside the "Description" section, and added some info about connectedMoveCallback() to the custom elements page. I didn't add it to the Document.moveBefore() page as it didn't seem so relevant there, just DocumentFragment... and Element...

* We should say something about the constraints: `moveBefore` only works within the same document, and it cannot work as a way to connect or disconnect an element. Moving a disconnected element to a connected parent or vice versa, would result in an exception. Users of this API that want to be resilient to this need to know in advance whether they're acting across disconnected/connected state, across documents, and use `insertBefore` instead in these cases (or try/catch the `moveBefore`).

I've added a section about constraints to the "Description" section, and also tried to move sure the relevant exceptions are represented in the "Exceptions" section.

* As far as mutation observers go, there is no particular change, but it might be worthwhile to note that the moved element would appear as removed/re-inserted in mutation observers.

Good call; I've added a note about this.

[chrisdavidmills]

@noamr ^

[noamr]

Perhaps reword to "interactivity"

[chrisdavidmills]

Updated to

• Interactivity states (for example, {{cssxref(":focus")}} and {{cssxref(":active")}}).

[noamr]

constraints

[chrisdavidmills]

Oops! Fixed.

[noamr]

"care needs to be taken" is not the right framing here.
By default, custom elements don't support state-preserving move, and their disconnected and connected callbacks are fired.

Authors of web components can opt in to state-preserving move behavior, by implementing the connectedMoveCallback, which would be called instead of the disconnected+connected default.

Note: this default behavior is introduced in order to maintain backwards compatibility with existing custom elements who might rely on being disconnected and reconnected when moved around the DOM.

[chrisdavidmills]

OK, I get this now; thanks for the explanation. I've reworded the section as follows:

---

Moving custom elements

Each time a custom element is moved via moveBefore() (or similar methods such as {{domxref("Node.insertBefore()")}}), the disconnectedCallback() and connectedCallback() lifecycle callbacks are fired.

Consider this minimal example:

class MyCustomElement extends HTMLElement {
  constructor() {
    super();
  }

  connectedCallback() {
    console.log("Custom element added to page.");
  }

  disconnectedCallback() {
    console.log("Custom element removed from page.");
  }
}

customElements.define("my-custom-element", MyCustomElement);

In this case, "Custom element removed from page." and "Custom element added to page." are logged to the console with each move. This might be your intended behavior. However, if you use the callbacks to run initialization and cleanup code, it might cause problems with the state of the moved element.

Custom elements can be opted in to state-preserving moves via the connectedMoveCallback() lifecycle callback. If defined in the constructor, this will run instead of connectedCallback() and disconnectedCallback() when an element instance is moved via moveBefore(). You could add an empty connectedMoveCallback() to stop the other two callbacks running, or include some custom logic to handle the move:

connectedMoveCallback() {
  console.log("Custom element moved with moveBefore()");
}

[noamr]

Perfect thanks!

[noamr]

• When defined, called _instead etc..

[chrisdavidmills]

updated

[chrisdavidmills]

Thanks a lot for the review, @noamr. I think this is ready for editorial review now, so I will move it on to that stage, but feel free to chime in if you spot anything else.