Update HTMLSlotElement.assign() documentation

[trusktr]

Clarified behavior of assign() method regarding fallback content and slot assignments.

Description

There was no indication of what calling assign() with zero args does, so I added it.

Motivation

The spec doesn't seem to mention it either.

Additional details

I tested this in Safari:

https://codepen.io/editor/trusktr/pen/019fe93d-5654-74d2-ad78-473bf9e632fa

Notice the setTimeout removes the only slotted node from the slot after 1 second, but the slot's fallback content is not shown. This is a state that is unreachable via declarative slot assignment.

Uncomment the slot.assign() call to see that fallback content is shown only when assign() is called with no args (not when all assigned nodes are removed).

Related issues and pull requests

[github-actions]

Preview URLs (1 page)

• /en-US/docs/Web/API/HTMLSlotElement/assign

(comment last updated: 2026-09-11 04:55:42)

[Copilot]

Pull request overview

Updates the MDN documentation for HTMLSlotElement.assign() to clarify behavior around empty assignments and fallback content in manual slot assignment mode.

Changes:

• Expanded the method description to discuss fallback content behavior when calling assign() with no arguments.
• Updated the Syntax and Parameters sections to document the zero-argument call pattern.
• Adjusted the example to call assign() with no arguments when there are no panels to assign.

Suppressed comments (2)

files/en-us/web/api/htmlslotelement/assign/index.md:22

• The Syntax block format here (slot.assign(...)) is inconsistent with the other HTMLSlotElement instance-method pages, which list the method signatures without a receiver (e.g., assignedNodes() at files/en-us/web/api/htmlslotelement/assignednodes/index.md:17-20 and assignedElements() at files/en-us/web/api/htmlslotelement/assignedelements/index.md:19-22). For consistency across the interface docs, consider using assign(...) signatures here too.

slot.assign() // enables fallback content
slot.assign(node1)
slot.assign(node1, node2)
slot.assign(node1, node2, /* …, */ nodeN)

files/en-us/web/api/htmlslotelement/assign/index.md:31

• slot shouldn't be listed as a parameter here: assign() is an instance method, so the receiver is implicit (consistent with the other HTMLSlotElement method pages). Also, the node1…nodeN item currently has two separate description markers (- :), which breaks the MDN definition-list formatting.

- `slot`
  - : The {{domxref("HTMLSlotElement")}} to assign nodes to.
- `node1`, …, `nodeN`
  - : A set of {{domxref("Element")}} or {{domxref("Text")}} nodes.
  - : Passing zero arguments causes the slot's fallback content to be enabled. Failing to call **`assign()`** with zero arguments after all manually assigned nodes are removed from DOM will *not* enable the slot's fallback content.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[trusktr]

Turns out the behavior I'm describing (and apparently the pre-existing example) are based on Safari behavior. Maybe we need clarification in the spec, and WPTs to iron it out.

Should removing all slotted nodes from light DOM automatically update slots in shadow DOM so that the slots will show their fallback content without an armless assign() call?

[Josh-Cena]

Thanks. I can only reproduce this behavior on Safari, but not on Chrome or Firefox, so I will assume it's a Safari bug. (https://dom.spec.whatwg.org/#concept-node-remove requires running assign slottables, but WebKit did not invalidate the render state.) Please consider reporting it to Safari. Meanwhile I've changed the example to a live sample. Mentioning you can call assign() without arguments is definitely helpful.