Add shadowrootslotassignment attribute

[keithamus]

Description

This adds docs for the shadowrootslotassignment attribute.

Motivation

Trying to add the docs so that whatwg/html#12267 can be merged.

Additional details

I've largely cribbed the docs style from the other shadowroot* attributes.

Related issues and pull requests

• Add HTMLTemplateElement.shadowrootslotassignment attribute browser-compat-data#29457
• [WebAPI] Enable shadowrootslotassignment by default #43866

[pepelsbey]

Thank you. Is there an existing browser implementation? It seems to be missing from BCD for now.

[pepelsbey]

It seems like it's not implemented yet. So I would keep this PR open until the first experimental implementation lands, as we only document features supported by browsers. Thank you again for doing this in advance!

[keithamus]

It seems like it's not implemented yet. So I would keep this PR open until the first experimental implementation lands, as we only document features supported by browsers. Thank you again for doing this in advance!

Right. https://groups.google.com/a/mozilla.org/g/dev-platform/c/8qxAHE9-Xdo is my intent to ship this in Firefox. I'll work on adding BCD definitions.

[github-actions]

Preview URLs (6 pages)

• /en-US/docs/Web/API/Element/attachShadow
• /en-US/docs/Web/API/HTMLTemplateElement/shadowRootSlotAssignment
• /en-US/docs/Web/API/HTMLTemplateElement
• /en-US/docs/Web/API/ShadowRoot/slotAssignment
• /en-US/docs/Web/HTML/Reference/Elements/slot
• /en-US/docs/Web/HTML/Reference/Elements/template

External URLs (1)

URL: /en-US/docs/Web/HTML/Reference/Elements/slot
Title: <slot> HTML web component slot element

• https://w3c.github.io/html-aria/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-05-08 04:24:37)

[ddbeck]

This PR was was quite helpful for me while trying to figure how to assign shadowrootslotassignment into web-features. Thank you! But after reading this, it sounds like it does have some utility to developers and it might be better to start with that information. Something along these lines:

The shadowRootSlotAssignment property of the HTMLTemplateElement interface reflects the value of the shadowrootslotassignment attribute of the associated <template> element. You can use its existence to detect support for the shadowrootslotassignment attribute.

You can't use this to use this to change…

(This is a drive-by suggestion from someone who knows very, very little about the shadow DOM. Take it with a grain of salt. 😅)

[hamishwillee]

UPdated in 2f3331a to show the only use - feature checking

[hamishwillee]

I wasn't originally assigned to this PR, so I wasn't going to comment.

My problem with this PR is that after reading it I really don't understand what this feature actually does. I was hoping to find the information at this point. It looks like I would have to go to Element.attachShadow() for more detail. Perhaps just a little more detail here would be useful. If not, then all the other links to here need to also point to attachShadow() (including the JavaScript interfaces) to reduce the steps to finding examples etc.

On that note, and example below in this doc would be great.

[hamishwillee]

Two ways to do this now right? Something like ...

Suggested change

	The read-only **`slotAssignment`** property of the {{domxref("ShadowRoot")}} interface returns the _slot assignment mode_ for the shadow DOM tree. Nodes are either automatically assigned (`named`) or manually assigned (`manual`).
	The value of this property is defined using the `slotAssignment` option when calling {{domxref("Element.attachShadow()")}}, or using the [`shadowrootslotassignment` attribute](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootslotassignment) on {{htmleelement("template")}} when declaratively creating a shadow root.

[hamishwillee]

@keithamus THanks for this. I'm supported to sort out docs for the FF151 release - have updated BCD and release note. Let me know what help you need to push this over the line.

[keithamus]

@hamishwillee happy to have you take over this PR if you have time. I won’t be able to get to it until late next week or so.

[hamishwillee]

@hamishwillee happy to have you take over this PR if you have time. I won’t be able to get to it until late next week or so.

Hi @keithamus

I've updated it "a bit" to what I consider a reasonable minimum - i.e. the point where I understand what is going on here:-)

Specifically I've added examples to the template doc on how this is used, and also on attachShadow() - but only for the named slot assignment case. I know that doesn't actually "say" anything extra, but live examples are like a picture that tells many words.

This needs your review, and then perhaps we should get an independent review from Vadim.

What is missing though is some explanation of why you would ever use manual assignment. There must be good reasons, and it would be great to explain them - and when you would use/not use the feature.

It might make sense to include this in https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements - that could then be the master copy we link to for this kind of stuff.

[hamishwillee]

@keithamus Did you see my comment above? ^^^

@pepelsbey Do you think you could review? I could just approve this, but as per #43753 (comment) I did some edits and might be a bit "too close" to the text to be objective now.

[keithamus]

What is missing though is some explanation of why you would ever use manual assignment. There must be good reasons, and it would be great to explain them - and when you would use/not use the feature.

Put simply: if you want different heuristics for slot assignment, rather than the stock slot= attribute. There are two main benefits to deviating from this:

1. More ergonomic slot assignment, using co-operative elements or heuristics like the element name or a query selector. This means the light dom doesn't need slot= attributes everywhere.
2. Dynamic slot assignment, where the HTML structure remains static but slots get swapped in and out based on interaction or some other state.

For example you might have a set of tab components which co-operate with one another, such as:

<tab-container>
	<button>One</button>
	<button>Two</button>
	<tab-panel>One's content</tab-panel>
	<tab-panel>Two's content</tab-panel>
</tab-container>

Without manual assignment you'd you'd need to sprinkle slot=tabs, slot=panels everywhere, and the <tab-container> would need to mutate the <tab-panel> elements to add/remove slot attributes, which would cause other side effects such as MutationObservers running, etc.

Another example to demonstrate dynamic slot assignment could be something like a movie picker, where you can filter movies by genre, where movies have multiple dramas:

<movie-picker>
	<label>Genre:
		<select>
			<option>Comedy</option>
			<option>Drama</option>
			<option>Action</option>
			<option>Romance</option>
		</select>
	</label>
	<div data-genre="comedy romance"><h2>Hungover on Valentine's Day</h2></div>
	<div data-genre="drama romance"><h2>Us Two, plus Three</h2></div>
	<div data-genre="action drama"><h2>The Hitman 2: Can't die twice</h2></div>
	<div data-genre="action comedy"><h2>Tinkerbell, the last action hero</h2></div>
</movie-picker>

The element could use manual slot assignment to detect a change event in the select, and slot only the elements who's data-genre matches, thereby not rendering elements that don't match.