From 92ca7f122278fb1770fad02491c165173612c178 Mon Sep 17 00:00:00 2001 From: Joe Pea Date: Sun, 9 Aug 2026 18:46:27 -0700 Subject: [PATCH 1/5] Update HTMLSlotElement.assign() documentation Clarified behavior of assign() method regarding fallback content and slot assignments. --- .../en-us/web/api/htmlslotelement/assign/index.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/files/en-us/web/api/htmlslotelement/assign/index.md b/files/en-us/web/api/htmlslotelement/assign/index.md index 8b304a350063de2..f4d6e9828d7f225 100644 --- a/files/en-us/web/api/htmlslotelement/assign/index.md +++ b/files/en-us/web/api/htmlslotelement/assign/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLSlotElement.assign {{APIRef("Shadow DOM API")}} -The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets the slot's _manually assigned nodes_ to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`. +The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets the slot's _manually assigned nodes_ to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`. If no slottables are passed into **`assign()`**, the slot's fallback content is enabled. If there are no manually assigned nodes and **`assign()`** has not been called, the slots default content will not be enabled. > [!NOTE] > You cannot mix manually (imperative) and named (declarative, automatic) slot assignments. Therefore, for this method to work, the shadow tree needs to have been [created](/en-US/docs/Web/API/Element/attachShadow) with the `slotAssignment: "manual"` option. @@ -16,15 +16,19 @@ The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets t ## Syntax ```js-nolint -assign(node1) -assign(node1, node2) -assign(node1, node2, /* …, */ nodeN) +slot.assign() // enables fallback content +slot.assign(node1) +slot.assign(node1, node2) +slot.assign(node1, node2, /* …, */ nodeN) ``` ### Parameters +- `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. ### Return value @@ -47,6 +51,8 @@ function UpdateDisplayTab(elem, tabIdx) { if (panels.length && tabIdx && tabIdx <= panels.length) { slot.assign(panels[tabIdx - 1]); } else { + // In case there are no nodes to assign, call `assign()` with zero arguments + // to enable the slot's fallback content. slot.assign(); } } From 1b493e5cef563bd6b7ee25de3e0beaedd87e0d2b Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 10 Sep 2026 21:04:54 -0700 Subject: [PATCH 2/5] Fix bad content --- .../web/api/htmlslotelement/assign/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/files/en-us/web/api/htmlslotelement/assign/index.md b/files/en-us/web/api/htmlslotelement/assign/index.md index f4d6e9828d7f225..1a9c6ef2a5fe1e7 100644 --- a/files/en-us/web/api/htmlslotelement/assign/index.md +++ b/files/en-us/web/api/htmlslotelement/assign/index.md @@ -8,7 +8,9 @@ browser-compat: api.HTMLSlotElement.assign {{APIRef("Shadow DOM API")}} -The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets the slot's _manually assigned nodes_ to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`. If no slottables are passed into **`assign()`**, the slot's fallback content is enabled. If there are no manually assigned nodes and **`assign()`** has not been called, the slots default content will not be enabled. +The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets the slot's _manually assigned nodes_ to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`. + +If no slottables are passed into `assign()`, the slot's fallback content is enabled. If there are no manually assigned nodes and `assign()` has not been called, the slots default content will not be enabled. > [!NOTE] > You cannot mix manually (imperative) and named (declarative, automatic) slot assignments. Therefore, for this method to work, the shadow tree needs to have been [created](/en-US/docs/Web/API/Element/attachShadow) with the `slotAssignment: "manual"` option. @@ -16,19 +18,17 @@ The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets t ## Syntax ```js-nolint -slot.assign() // enables fallback content -slot.assign(node1) -slot.assign(node1, node2) -slot.assign(node1, node2, /* …, */ nodeN) +assign() +assign(node1) +assign(node1, node2) +assign(node1, node2, /* …, */ nodeN) ``` ### Parameters -- `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. + 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. ### Return value From 25e2d2b557c7688aa1527efbffe5287841823e59 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 10 Sep 2026 21:24:55 -0700 Subject: [PATCH 3/5] Make live sample --- .../web/api/htmlslotelement/assign/index.md | 83 +++++++++++++++++-- 1 file changed, 75 insertions(+), 8 deletions(-) diff --git a/files/en-us/web/api/htmlslotelement/assign/index.md b/files/en-us/web/api/htmlslotelement/assign/index.md index 1a9c6ef2a5fe1e7..5d88ee8b7bc61f6 100644 --- a/files/en-us/web/api/htmlslotelement/assign/index.md +++ b/files/en-us/web/api/htmlslotelement/assign/index.md @@ -10,8 +10,6 @@ browser-compat: api.HTMLSlotElement.assign The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets the slot's _manually assigned nodes_ to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`. -If no slottables are passed into `assign()`, the slot's fallback content is enabled. If there are no manually assigned nodes and `assign()` has not been called, the slots default content will not be enabled. - > [!NOTE] > You cannot mix manually (imperative) and named (declarative, automatic) slot assignments. Therefore, for this method to work, the shadow tree needs to have been [created](/en-US/docs/Web/API/Element/attachShadow) with the `slotAssignment: "manual"` option. @@ -27,8 +25,9 @@ assign(node1, node2, /* …, */ nodeN) ### Parameters - `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. + - : A set of {{domxref("Element")}} or {{domxref("Text")}} nodes. Passing zero arguments clears the slot's manually assigned nodes, and its fallback content is displayed. Fallback content is also displayed when no nodes have been assigned or all assigned nodes have been removed from the shadow host. + + Removing a node from the shadow host preserves its manual assignment, so reinserting it into the host restores its slot assignment unless the manual assignment has been changed using `assign()`. ### Return value @@ -41,23 +40,91 @@ None ({{jsxref("undefined")}}). ## Examples -In the example below, the `assign()` method is used to display the correct tab in a tabbed application. The function is called and passed the panel to show, which is then assigned to the slot. +### Displaying assigned nodes and fallback content + +In this example, the `assign()` method is used to display one of two panels. Click a panel button to assign that panel to the slot, or click "Show fallback" to clear the assignment and display the slot's fallback content. Switching panels or clearing the assignment does not remove the panels from the shadow host. + +To compare clearing an assignment with removing a node, first display a panel, then click "Remove assigned panel". This removes the panel from the shadow host without calling `assign()`. The fallback content should appear automatically. If the output is blank instead, click "Show fallback" to see whether explicitly clearing the assignment restores it. Clicking any other button first restores any removed panels to the shadow host, then updates the slot assignment. + +#### HTML + +```html +
+ + + + +
+ +
+

This is the first panel.

 +

This is the second panel.

 +
+``` + +#### JavaScript ```js -function UpdateDisplayTab(elem, tabIdx) { +function updateDisplayTab(elem, tabIdx) { const shadow = elem.shadowRoot; const slot = shadow.querySelector("slot"); const panels = elem.querySelectorAll("tab-panel"); if (panels.length && tabIdx && tabIdx <= panels.length) { slot.assign(panels[tabIdx - 1]); } else { - // In case there are no nodes to assign, call `assign()` with zero arguments - // to enable the slot's fallback content. + // Clear any previous assignment to display the slot's fallback content. slot.assign(); } } + +const host = document.querySelector("#panels"); +const panels = host.querySelectorAll("tab-panel"); +const shadow = host.attachShadow({ + mode: "open", + slotAssignment: "manual", +}); +shadow.innerHTML = ` + +

This is the fallback content. No panel is assigned.

+ +`; +const slot = shadow.querySelector("slot"); + +function restorePanels() { + for (let i = panels.length - 1; i >= 0; i--) { + if (panels[i].parentNode !== host) { + host.insertBefore(panels[i], panels[i + 1] ?? null); + } + } +} + +document.querySelector("#show-first").addEventListener("click", () => { + restorePanels(); + updateDisplayTab(host, 1); +}); + +document.querySelector("#show-second").addEventListener("click", () => { + restorePanels(); + updateDisplayTab(host, 2); +}); + +document.querySelector("#show-fallback").addEventListener("click", () => { + restorePanels(); + updateDisplayTab(host, 0); +}); + +document.querySelector("#remove-panel").addEventListener("click", () => { + for (const panel of slot.assignedNodes()) { + // Remove the node without clearing its manual assignment. + panel.remove(); + } +}); ``` +#### Result + +{{EmbedLiveSample("Displaying assigned nodes and fallback content", "100%", 150)}} + ## Specifications {{Specifications}} From 4ecd8150b4fab121448a16798bdf3a2e9729f9e0 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 10 Sep 2026 21:39:56 -0700 Subject: [PATCH 4/5] Remove Safari behavior note --- files/en-us/web/api/htmlslotelement/assign/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/htmlslotelement/assign/index.md b/files/en-us/web/api/htmlslotelement/assign/index.md index 5d88ee8b7bc61f6..32cdc7d7fc32b68 100644 --- a/files/en-us/web/api/htmlslotelement/assign/index.md +++ b/files/en-us/web/api/htmlslotelement/assign/index.md @@ -44,7 +44,7 @@ None ({{jsxref("undefined")}}). In this example, the `assign()` method is used to display one of two panels. Click a panel button to assign that panel to the slot, or click "Show fallback" to clear the assignment and display the slot's fallback content. Switching panels or clearing the assignment does not remove the panels from the shadow host. -To compare clearing an assignment with removing a node, first display a panel, then click "Remove assigned panel". This removes the panel from the shadow host without calling `assign()`. The fallback content should appear automatically. If the output is blank instead, click "Show fallback" to see whether explicitly clearing the assignment restores it. Clicking any other button first restores any removed panels to the shadow host, then updates the slot assignment. +To compare clearing an assignment with removing a node, first display a panel, then click "Remove assigned panel". This removes the panel from the shadow host without calling `assign()`. The fallback content should appear automatically. Clicking any other button first restores any removed panels to the shadow host. #### HTML From 8e7293abffbecba8e9f49dec4af5a8f7a6437546 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 10 Sep 2026 21:53:15 -0700 Subject: [PATCH 5/5] Does not throw error --- files/en-us/web/api/htmlslotelement/assign/index.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/files/en-us/web/api/htmlslotelement/assign/index.md b/files/en-us/web/api/htmlslotelement/assign/index.md index 32cdc7d7fc32b68..e859bdfe4e5f420 100644 --- a/files/en-us/web/api/htmlslotelement/assign/index.md +++ b/files/en-us/web/api/htmlslotelement/assign/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLSlotElement.assign The **`assign()`** method of the {{domxref("HTMLSlotElement")}} interface sets the slot's _manually assigned nodes_ to an ordered set of slottables. The manually assigned nodes set is initially empty until nodes are assigned using `assign()`. > [!NOTE] -> You cannot mix manually (imperative) and named (declarative, automatic) slot assignments. Therefore, for this method to work, the shadow tree needs to have been [created](/en-US/docs/Web/API/Element/attachShadow) with the `slotAssignment: "manual"` option. +> Manual assignments determine the slot's displayed content only when the shadow tree has been [created](/en-US/docs/Web/API/Element/attachShadow) with the `slotAssignment: "manual"` option. In a shadow tree using named (automatic) assignment, calling `assign()` still updates the slot's manually assigned nodes, but does not override named assignment. ## Syntax @@ -33,11 +33,6 @@ assign(node1, node2, /* …, */ nodeN) None ({{jsxref("undefined")}}). -### Exceptions - -- `NotAllowedError` {{domxref("DOMException")}} - - : Thrown when calling this method on an automatically assigned slot. - ## Examples ### Displaying assigned nodes and fallback content