Accordion Component

11 | 12 |

About this Document

13 |

14 | 15 |

All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.

16 | 17 |

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification.

18 | 19 |

To help with layering and to avoid circular dependencies between various parts of specification, this document consists of three consecutive narratives: 20 |

setting up the stage for the specification,
explaining of the conceptual model and algorithms behind it, and
expressing this model with DOM interfaces and HTML elements.

25 |

In a sense, these parts can be viewed as math, which sets up the reasoning environment, physics, which is the theoretical reasoning about the concept, and mechanics, which is the is the practical application of this reasoning.

26 | 27 |

Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.

28 | 29 |

30 |

Dependencies

31 |

32 | 33 |

This document relies on the following specifications:

34 | 35 |

45 | 46 |

47 |

Terminology

48 |

49 | 50 |

The following terms are used throughout the specification: 51 | 52 |

DOM: The document object model
document: The Document Object Model's underlying document
node: Any DOM object that participates in a tree
element: A DOM object that implements the Element interface
DOM tree: Any tree, composed of DOM objects 63 |
DOM structure: A DOM tree or fragment of a DOM tree 65 |

66 | 67 |

68 |

Introduction

69 |

70 | 71 |

Web application developers often encounter the need to provide encapsulation of a DOM structure. Despite being part of one document tree, there are typically many functional fragments of DOM (or DOM subtrees), as well as assumptions about these fragments operating independently. This type of encapsulation is called functional encapsulation, as opposed to trust encapsulation, which deals with limiting information flow based on trust and ensuring security of data and state within an application.

72 | 73 |

Functional encapsulation is primarily concerned with establishing functional boundaries in a document tree. A functional boundary (or just boundary hereon) is a delineation of functional concerns between two loosely coupled units of functionality.

74 | 75 |

Functional Encapsulation Example

76 | 77 |

A Web application user interface is commonly composed of several user interface elements (or widgets), each a DOM subtree. In cases where a widget is tasked with hosting other widgets, the need arises for the widget to understand where its DOM subtree ends and another widget's DOM subtree begins.

78 | 79 |

This need for observing the functional boundaries in a document tree is even larger when a widget is operated on—added, moved, or removed in the document tree—by an outside actor, such as the Web application that consumes these widgets. Unless the widget consumer knows exactly how a widget's DOM structure is designed, it is impossible for the consumer to reasonably operate on the widget. A typical workaround has been providing alternative means of operation by the widget developer, which, in striving for API consistency quickly extrapolates into a complete set of widget-specific, DOM-like APIs.

80 | 81 |

82 |

Shadow DOM Subtrees

83 |

84 | 85 |

To solve this problem at its core, a new abstraction is introduced. The shadow DOM allows multiple DOM subtrees (in addition to the document tree) to be composed into one larger tree when rendered. The existence of multiple DOM subtrees is enabled by letting any element in the document tree to host one or more additional DOM subtrees. These shadow DOM subtrees are governed by a set of rules that establish encapsulation boundaries while retaining the standard DOM composability semantics.

86 | 87 |

The encapsulation boundaries between shadow DOM subtrees are called shadow boundaries. The elements that host shadow DOM subtrees are called shadow hosts, and the root nodes of the shadow DOM subtrees are called shadow roots.

88 | 89 |

When rendered, the shadow DOM subtree takes place of the host element's content.

90 | 91 |

To enable composition of host element's children and the shadow DOM subtree, a notion of insertion points is added to the abstraction. An insertion point is a defined location in the shadow DOM subtree, to which the host element's children are transposed when rendering.

92 | 93 |

Thus, the encapsulation of a shadow DOM subtree can be viewed as a two-fold problem: 94 |

the upper-boundary encapsulation, or governing the boundary between the shadow root and the shadow host; and
the lower-boundary encapsulation, or governing the boundary between the insertion points and the shadow host's children.

98 | 99 |

Upper-boundary Encapsulation

100 | 101 |

To maintain the upper-boundary encapsulation, the following scoping constraints must apply to all nodes in a shadow DOM subtree:

102 |

The ownerDocument property refers to the document of the shadow host
The nodes and named elements are not accessible using shadow host's document DOM tree accessors
The nodes with a unique id and named elements are not addressable from any attributes of elements in shadow host's document
The stylesheets, represented by the nodes are not accessible using shadow host document's CSSOM extensions
The nodes are accessible using shadow root's DOM tree accessor methods
The nodes with a unique id and named elements are addressable from any attributes of elements in the same shadow DOM subtree
The selectors must not cross the shadow boundary

111 |

For convenience, the shadow root provides its own set of DOM tree accessor methods. No nodes other than shadow root descendants are accessible with these methods.

112 | 113 |

The parentNode and parentElement attributes of the shadow root object must always return null.

114 | 115 |

Lower-boundary Encapsulation

116 | 117 |

To maintain the lower-boundary encapsulation, the distribution of child nodes of the shadow host among the insertion points in the associated shadow DOM subtree must have the following traits:

118 |

The distribution does not affect the state of the document DOM tree or shadow DOM subtrees
Each insertion point participates in distribution by providing a matching criteria for the child nodes. The matching criteria determines whether a given node could be distributed to a given insertion point
The distribution is a result of executing a stable algorithm
The distribution itself does not change the variables affecting the distribution
The distribution reoccurs whenever any variable affecting it is changed

125 | 126 |

An insertion point may be active or inactive. An active insertion point participates in the distribution process, whereas the inactive insertion does not. If not specifically set to be inactive, the insertion point must be considered active.

127 | 128 | The distribution algorithm must produce an outcome that is equivalent of the outcome of processing these steps:

129 | 130 |

131 |

Input: TREE, a shadow DOM subtree; POOL, a list of DOM nodes
Output: The nodes in POOL are distributed among insertion points in TREE.

138 | 139 |

Repeat for each active insertion point in TREE, in tree order: 141 |
1. Let POINT be the current insertion point
2. Repeat for each node in POOL: 144 |
  1. Let NODE be the current node
  2. If the NODE matches POINT's matching criteria:
  3. Otherwise, continue to repeat
3. Continue to repeat

156 |

157 | 158 |

Matching Insertion Points

159 | 160 |

The matching criteria for insertion point is defined as a set of selector fragments. Each selector fragment is indeed a fragment in the selector (shadow-host)>(fragment), where (shadow-host) is a selector that uniquely identifies the shadow host, and (fragment) is the selector fragment.

161 | 162 |

A valid selector fragment may contain:

163 | 164 |

A type selector or a universal selector
class selector(s)
An ID selector
attribute selector(s)
the following pseudo-class selector(s): 170 |
- :link
- :visited
- :target
- :enabled
- :disabled
- :checked
- :indeterminate
- :nth-child()
- :nth-last-child()
- :nth-of-type()
- :nth-of-last-type()
- :first-child
- :last-child
- :first-of-type
- :last-of-type
- :only-of-type
188 |

190 | 191 |

If any other types of selectors are present the selector fragment, the fragment must be considered invalid.

192 | 193 |

A conforming UAs must consider a node as matching a set of selector fragments in the context of a given shadow host, if it: 194 |

is a child node of the shadow host; and
all selector fragments in the set are valid; and
child node matches at least one selector fragment in the set or the set is empty.

199 | 200 | 201 |

Hosting Multiple Shadow Subtrees

202 | 203 |

A shadow host may host more than one shadow DOM subtree. In such cases, the subtrees are stacked in the order they were added the the host, starting with the subtree added most recently. This set of trees is called a tree stack. The more recently added subtree is called the younger tree, and the less recently added subtree is called the older tree. The most recently added subtree is called the youngest tree.

204 | 205 |

To facilitate composing multiple shadow subtrees of the same host, a special kind of insertion point is defined. The shadow insertion point designates a place in the shadow DOM subtree, where an older tree is inserted.

206 | 207 |

Just like other insertion points, the shadow insertion points can be active or inactive.

208 | 209 |

The composition is performed with the tree composition algorithm, which must be equivalent to processing the following steps: 210 | 211 |

212 |

Input: HOST, a shadow host
Output: All insertion points and shadow insertion points are populated.

218 | 219 |

Let TREE be the youngest tree in the HOST's tree stack 221 |
Let POOL be the list of nodes
Populate POOL with child nodes of the HOST
Repeat while TREE exists:

Let POINT be the first encountered active shadow insertion point in TREE, in tree order 226 |
Run the distribution algorithm, supplying POOL and TREE as input
If POINT exists: 228 |
1. Find the next older tree, relative to TREE in the HOST's tree stack 230 |
  1. If there is no older tree: 232 |
    1. Distribute remaining nodes in POOL, if any, to POINT
    2. stop.
  2. Otherwise: 237 |
    1. Set TREE to be this older tree
    2. Assign TREE to the POINT
    3. Continue to repeat
Otherwise, stop. 245 |

247 |

248 | 249 |

When an insertion point or a shadow insertion point has nothing assigned or distributed to them, the fallback content must be used instead when rendering. The fallback content is all descendants of the DOM element that represents the insertion point. The insertion points or shadow insertion points in fallback content must be considered inactive.

250 | 251 |

Nested Shadow Subtrees

252 | 253 |

Any element in a shadow DOM subtree can be a shadow host, thus producing nested shadow DOM subtrees. A shadow DOM subtree is nested when its shadow host is itself a part of a shadow DOM subtree.

254 | 255 |

Rendering Shadow DOM Subtrees

256 | 257 |

Rendering of shadow DOM subtrees, or presenting them visually, is defined as a specialization of rendering any DOM subtree, and must happen as these steps:

258 | 259 |

260 |

Input: HOST, a shadow host
Output: Rendering of the HOST, including its shadow DOM subtrees

266 | 267 |

Run tree composition algorithm for the given shadow host
As content of the shadow host, render the youngest tree as a any DOM subtree, with the following shadow rendering exceptions: 270 |
- Each element that is a shadow host must be rendered accordingly
- In place of each insertion point, process the following insertion point rendering steps: 273 |
  1. If there are child nodes distributed to this insertion point, for each child node and in the order they were distributed: 275 |
    1. Let CHILD be the child node being rendered
    2. If CHILD is itself an insertion point, and the tree being rendered is nested, render them using insertion point rendering steps
    3. Otherwise, render CHILD as any DOM subtree 279 |
  2. Otherwise, render fallback content as any DOM subtree
- In place of each shadow insertion point: 283 |
  1. If there is an older tree, assigned to this shadow insertion point, render it as any DOM subtree, but with the same shadow rendering exceptions.
  2. Otherwise, render fallback content as any DOM subtree

289 |

290 | 291 |

This process of rendering produces a structure that is a composition of several DOM subtrees, including the document tree. The term "as rendered" is used to refer to this structure.

292 | 293 |

294 |

Events

295 |

296 | 297 |

In shadow DOM subtrees, the DOM Events are allowed to cross the shadow boundaries under some conditions.

298 | 299 |

When an event is fired in a shadow DOM subtree, it either escapes out of the shadow tree during the capture, target, or bubble phases or it is stopped at the shadow boundary.

300 | 301 |

In terms of DOM event dispatch, this manifests in populating the list of ancestors of the target node with adjusted parent nodes, or nodes that appear as parents as rendered. The parent calculation algorithm is used to determine the adjusted parent of any given node and create the list of ancestors for event dispatch. This algorithm must be equivalent to processing the following steps:

302 | 303 |

304 |

Input: NODE, a DOM node
Output: PARENT, a DOM node's adjusted parent

310 |

If NODE is currently distributed to an insertion point in a shadow DOM subtree 312 |
1. Let the PARENT be the insertion point to which the NODE is distributed to
If NODE is a shadow root: 316 |
1. If NODE is currently assigned to a shadow insertion point: 318 |
  1. Let the PARENT be the shadow insertion point to which NODE is assigned to
2. Otherwise, let the PARENT be the shadow host of the NODE 322 |
Otherwise, let PARENT be the node's parent node.

325 |

326 | 327 |

Event Retargeting

328 | 329 |

In the cases where event escapes the shadow tree, the event's information about the target of the event is adjusted in order to maintain upper boundary encapsulation. Event retargeting is a process of computing relative targets for each ancestor of the node at which the event is dispatched. A relative target is a DOM node that most accurately represents the target of a dispatched event at a given ancestor while maintaining the upper boundary encapsulation. 330 | 331 |

The retargeting algorithm is used to determine relative targets, and it must be equivalent to processing the following steps:

332 | 333 |

334 |

Input: NODE, a DOM node
Output: TARGETS, a list of tuples, each containing NODE's ancestor and its relative target

340 |

Let BOUNDARY be a flag, initialized to false
Let TARGET be NODE 344 |
Let ANCESTOR be NODE
Repeat while ANCESTOR exists: 346 |
1. If ANCESTOR is a shadow root, set BOUNDARY to true
2. Otherwise: 349 |
  1. If BOUNDARY is set to true 351 |
    1. Set TARGET to ANCESTOR
    2. Set BOUNDARY to false state
  2. Add (TARGET, ANCESTOR) tuple to TARGETS
3. Set ANCESTOR to be the result of parent calculation algorithm, given ANCESTOR as input

361 | 362 |

The retargeting process must occur prior to dispatch of an event.

363 | 364 |

Retargeting `relatedTarget`

365 | 366 |

Some events have a relatedTarget property, which holds a node that's not the event's target, but is related to the event.

367 | 368 |

For instance, a mouseover event's relatedTarget may hold the node from which the mouse has moved to event's target. In the case where relatedTarget is in a shadow DOM subtree, the conforming UAs must not leak its actual value outside of this subtree. In cases where both relatedTarget and target are part of the same shadow DOM subtree, the conforming UAs must stop events at the shadow boundary to avoid the appearance of spurious mouseover and mouseout events firing from the same node.

369 | 370 |

Thus, if an event has a relatedTarget, its value and extent of event dispatch must be adjusted. In general:

371 |

If relatedTarget and target are enclosed by a shadow DOM subtree, the event dispatch must be stopped at the shadow boundary of this subtree. This boundary is called lowest common boundary
If relatedTarget is separated from target by one or more shadow boundaries, it must be retargeted to the boundary that's closest to target. This boundary is called first divergent boundary.

375 | 376 |

The related target resolution algorithm is used to determine dispatch behavior of events with a relatedTarget property, which must be equivalent to processing the following steps:

377 | 378 |

379 |

Input: TARGET, the target DOM node of the event; RELATED, the related target DOM node of the event
Output: LIMIT, the ancestor DOM node of TARGET, at which the event dispatch must be stopped (not including LIMIT itself); ADJUSTED, the adjusted related target DOM node

387 |

Let COMMON be undefined
Let ANCESTOR be the lowest common ancestor of TARGET and RELATED, computed using parent calculation algorithm when determining ancestry
If ANCESTOR exists: 391 |
1. If ANCESTOR is RELATED and is a shadow host: 393 |
  1. Set LIMIT to ANCESTOR
  2. Set ADJUSTED to RELATED
  3. Stop.
2. Otherwise: 399 |
  1. Let ROOT be the nearest ancestor shadow root of ANCESTOR
  2. If ROOT exists, set COMMON and LIMIT to ROOT's shadow host
If COMMON is still undefined, set COMMON to the farthest ancestor of RELATED, computed using parent calculation algorithm when determining ancestry
Let HOST be the farthest shadow host ancestor of RELATED that is also a descendant of COMMON, computed using parent calculation algorithm when determining ancestry
If HOST exists, set ADJUSTED to HOST
Otherwise, set ADJUSTED to RELATED

409 |

410 | 411 |

Retargeting Focus Events

412 | 413 |

The focus, DOMFocusIn, blur, and DOMFocusOut events must be treated in the same way as events with a relatedTarget, where the corresponding node that is losing focus as a result of target gaining focus or the node that is gaining focus, and thus causing the blurring of target acts as the related target.

414 | 415 |

Events that are Always Stopped

416 | 417 |

Mutation events and selectstart event are always stopped at the nearest shadow boundary.

418 | 419 |

Event Dispatch

420 | 421 |

At the time of event dispatch:

422 |

The Event target and currentTarget attributes must return the relative target for the node on which event listeners are invoked
The UIEvent relatedTarget attribute must return the adjusted related target
When capturing, which entails processing step 3 of the event dispatch algorithm, the Event eventPhase attribute must return AT_TARGET if the relative target is same as the node on which event listeners are invoked
When bubbling, which entails processing step 6 of the event dispatch algorithm, the event listeners must not be invoked on a node if it is the same as its relative target

428 | 429 |

Upon completion of the event dispatch, the Event object's target and currentTarget must be to the highest ancestor's relative target. Since it is possible for a script to hold on to the Event object past the scope of event dispatch, this step is necessary to avoid revealing the nodes in shadow DOM subtrees.

430 | 431 |

Event Retargeting Example

432 | 433 |

Suppose we have a user interface for a media controller, represented by this DOM tree, composed of both document and the shadow DOM subtrees. In this example, we will assume that selectors are allowed to cross the shadow boundaries and we will use these selectors to identify the elements. Also, we will invent a fictional shadow-boundary element to demarcate the shadow boundaries:

434 |


435 | <div id="player">
436 |     <shadow-boundary>
437 |         <div class="controls">
438 |             <button class="play-button">
439 |             <input type="range" class="timeline">
440 |                 <shadow-boundary>
441 |                     <div class="slider-thumb"></div>
442 |                 </shadow-boundary>
443 |             </input>
444 |             <div class="volume-slider-container">
445 |                 <input type="range" class="volume-slider">
446 |                     <shadow-boundary>
447 |                         <div class="slider-thumb"></div>
448 |                     </shadow-boundary>
449 |                 </input>
450 |             </div>
451 |         </div>
452 |     </shadow-boundary>
453 | </div>
454 |

455 | 456 |

Let's have a user position their pointing device over the volume slider's thumb (#player .volume-slider .slider-thumb), thus triggering a mouseover event on that node. For this event, let's pretend it has no associated relatedTarget.

457 | 458 |

Just before the event is dispatched, we perform retargeting:

459 |

We set the relative target of the thumb node to itself.
Walking up, we find a shadow boundary and skip it.
Next up is an input (#player .volume-slider), and we set its relative target to itself, since the previous ancestor was a shadow boundary.
We then walk up to the containing div (#player .volume-slider-container), and use previous ancestor's target -- the input element.
Walking up one more, we reach the controls panel (#player .controls), and again use input element as relative target per retargeting algorithm.
Next, we reach another shadow boundary and skip it.
Finally we walk up to the player element (#player) and set its relative target to itself.

468 | 469 |


470 | <div id="player"> 7
471 |     <shadow-boundary> 6
472 |         <div class="controls"> 5
473 |             <button class="play-button">
474 |             <input type="range" class="timeline">
475 |                 <shadow-boundary>
476 |                     <div class="slider-thumb"></div>
477 |                 </shadow-boundary>
478 |             </input>
479 |             <div class="volume-slider-container"> 4
480 |                 <input type="range" class="volume-slider"> 3
481 |                     <shadow-boundary> 2
482 |                         <div class="slider-thumb"></div> 1
483 |                     </shadow-boundary>
484 |                 </input>
485 |             </div>
486 |         </div>
487 |     </shadow-boundary>
488 | </div>
489 |

490 | 491 |

492 | At the end of this process, we should have the following set of ancestors and relative targets: 493 |

494 | 495 | 496 | 497 | 498 | 499 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 509 | 510 | 511 | 512 | 513 | 514 | 515 | 516 | 517 | 518 | 519 | 520 | 521 | 522 | 523 | 524 | 525 | 526 | 527 |

Ancestor	Relative Target
`...`	`div#player`
`div#player`	`div#player`
`div#player .controls`	`div#player .controls .volume-slider`
`div#player .volume-slider-container`	`div#player .controls .volume-slider`
`div#player .controls .volume-slider`	`div#player .controls .volume-slider`
`div#player .controls .volume-slider .slider-thumb`	`div#player .controls .volume-slider .slider-thumb`

528 | 529 |

After we dispatch the mouseover event using these newly computed relative targets, the user decides to move their pointing device over the thumb of the timeline 530 | (#player .timeline .slider-thumb). This triggers both a mouseout event for the volume slider thumb and the mouseover event for the timeline thumb.

531 | 532 |

Let's study how the relatedTarget value of the volume thumb's mouseout event is affected and whether event escapes out of the player. For this event, the relatedTarget is the timeline thumb (#player .timeline .slider-thumb).

533 | 534 |

We find lowest common ancestor of timeline thumb and volume slider thumb: the controls panel (#player .controls).
Walking up, we look for a shadow boundary, and find one just above. This is the lowest common boundary.
Given that the lowest common boundary exists, we limit event dispatch to the descendants of this boundary.
Starting from the lowest common boundary, we walk down the ancestors of the timeline thumb, looking for a shadow boundary. We find it just below the timeline (#player .timeline). This is the first divergent boundary.
We adjust relatedTarget to be the parent of the first divergent boundary, the timeline (#player .timeline). We are now ready to dispatch this event.

541 | 542 |


543 | <div id="player">
544 |     <shadow-boundary> — lowest common boundary
545 |         <div class="controls">
546 |             <button class="play-button">
547 |             <input type="range" class="timeline">
548 |                 <shadow-boundary>  — first divergent boundary
549 |                     <div class="slider-thumb"></div>
550 |                 </shadow-boundary>
551 |             </input>
552 |             <div class="volume-slider-container">
553 |                 <input type="range" class="volume-slider">
554 |                     <shadow-boundary>
555 |                         <div class="slider-thumb"></div>
556 |                     </shadow-boundary>
557 |                 </input>
558 |             </div>
559 |         </div>
560 |     </shadow-boundary>
561 | </div>
562 |

563 | 564 |

565 |

Styles

566 |

567 | 568 |

To enforce upper-boundary encapsulation, CSS rules declared by the document do not apply in a shadow DOM subtree, unless the apply-author-styles flag is set for this subtree. The flag signals that document CSS rules are applicable in the shadow DOM subtree. 569 | 570 |

Conversely, to enforce lower-boundary encapsulation, CSS rules from a shadow DOM subtree do not apply to the nodes, distributed to the insertion points. 571 | 572 |

The rule applicability algorithm is used to determine whether any given rule is applicable to any DOM node, and it must be equivalent to processing the following steps:

573 | 574 |

575 |

Input: RULE, a CSS rule whose applicability is being determined; NODE, a DOM node
Output: Whether RULE must be applied to NODE. 581 |

582 |

If RULE is not an author style, the rule is applicable to NODE.
Otherwise: 585 |
1. Let TREE be the DOM subtree to which NODE belongs. The TREE is then the document tree, a shadow DOM subtree, or some disconnected tree
2. In the case TREE is a disconnected tree, the rule is not applicable to NODE.
3. In the case TREE is a shadow DOM subtree: 589 |
  1. If TREE has the apply-author-styles flag is set for TREE, RULE is applicable to NODE.
  2. Otherwise, if RULE is declared with a style element: 592 |
    1. Let STYLE be this style element
    2. If STYLE has a scoped attribute and STYLE is in TREE, then RULE is applicable to NODE.
  3. Otherwise, RULE is not applicable to NODE.
  598 |
4. In the case TREE is a document tree: 599 |
  1. If RULE is declared in TREE, the rule is applicable to NODE.
  2. Otherwise, RULE is not applicable to NODE.

605 |

606 | 607 |

The effect of this algorithm is that any unscoped styles, declared in a shadow DOM subtrees, are applied neither to document nor the subtree in which they are declared.

608 | 609 |

In a document that contains shadow DOM subtrees, the CSS properties must be inherited from parent nodes, produced using parent calculation algorithm. This requirement has the following effects:

610 |

the styles of the shadow host are inherited by the children of the shadow root
the styles of the insertion point node are inherited by those child nodes of the shadow host that are assigned to this insertion point
the styles of the shadow insertion point node are inherited by the child nodes of the shadow root of the shadow DOM subtree, distributed to this shadow insertion point

615 | 616 |

CSS Variables

617 | 618 |

The of shadow host styles being inherited by the children of the shadow root must also apply to CSS Variables. This provides a way for document DOM tree styles to send signals into the shadow DOM subtrees, and for the shadow DOM subtrees to receive these signals with the use of the data() function.

619 | 620 |

`text-decoration` Property

621 | 622 |

The text decorations, specified by the text-decoration property are not propagated from shadow hosts to shadow DOM subtrees.

623 | 624 |

625 |

User Interaction

626 |

627 | 628 |

Ranges and Selections

629 | 630 |

Since a DOM node in a document tree and a DOM node in a shadow DOM subtree never have the same root, there may never exist a valid DOM range that spans either both a document tree and a shadow DOM subtree, or multiple shadow DOM subtrees.

631 | 632 |

Accordingly, selections may only exist within one tree, because they are defined by a single range. To maintain upper boundary encapsulation, the selection, returned by the window.getSelection() method must never return a selection within a shadow DOM subtree.

633 | 634 | 635 | 636 |

Shadow DOM subtrees participate in sequential or directional focus navigation as part of the document tree. The navigation order within the shadow DOM subtrees must be determined using the as-rendered structure and is called shadow DOM navigation order.

637 | 638 |

For sequential focus navigation, the shadow DOM navigation order sequence must be inserted into the document navigation order:

639 |

immediately after the shadow host, if the shadow host is focusable; or
in place of the shadow host as if the shadow host were assigned the value of auto for determining its position.

643 | 644 |

For directional focus navigation, it is up to the user agent to integrate the shadow DOM navigation order into the document navigation order.

645 | 646 |

Editing

647 | 648 |

The value of the contenteditable attribute must not propagate from shadow host to its shadow DOM subtrees.

649 | 650 |

Assistive Technology

651 | 652 |

User agents with assistive technology traverse the document tree as rendered, and thus enable full use of of WAI-ARIA semantics in the shadow DOM subtrees.

653 | 654 |

655 |

HTML Elements in Shadow DOM Subtrees

656 |

657 | 658 |

Comparatively, a shadow DOM subtree can be seen as somewhere between just a DOM subtree in a document and a document fragment. Since it is rendered, a shadow DOM subtree aims to retain the traits of a typical DOM subtree in a document. At the same time, it is an encapsulation abstraction, so it has to avoid affecting the document DOM tree. Thus, the HTML elements behave as specified in the shadow DOM subtrees, with a few exceptions.

659 | 660 |

Inert HTML Elements

661 | 662 |

A subset of HTML elements behaves as inert, or not part of the document tree. This is consistent how the HTML elements would behave in a document fragment. These elements are:

663 |

base
link

667 | 668 |

All other HTML elements in the shadow DOM subtrees behave as if they were part of the document tree, though scoped to their subtrees.

669 | 670 |

HTML Forms

671 | 672 |

The forms in HTML are scoped at the document level. That is, all form elements and form-associated elements are accessible using the document DOM object's tree accessors. Per scoping constraints, this excludes elements in the shadow DOM subtrees.

673 | 674 |

Instead, each shadow DOM subtree scopes its form elements and form-associated elements. Because the form's ownerDocument is the shadow host's document, the form submission works as specified.

675 | 676 |

677 |

Elements and DOM Objects

678 |

679 | 680 |

`ShadowRoot` Object

681 | 682 |

The ShadowRoot object represents the shadow root.

683 | 684 |


685 | [Constructor(in HTMLElement host) raises (DOMException)]
686 | interface ShadowRoot : DocumentFragment {
687 |     HTMLElement getElementById(in DOMString elementId);
688 |     NodeList getElementsByClassName(in DOMString tagName);
689 |     NodeList getElementsByTagName(in DOMString className);
690 |     NodeList getElementsByTagNameNS(DOMString namespace, DOMString localName);
691 |     attribute bool applyAuthorStyles;
692 |     readonly attribute Element host;
693 |     attribute DOMString innerHTML;
694 | }
695 | ShadowRoot implements NodeSelector;
696 |

697 | 698 |

`ShadowRoot` Attributes

699 | 700 |

applyAuthorStyles of type bool: Represents the apply-author-styles flag and indicates whether or not the rules in author styles associated with the element's document apply to the shadow DOM subtree. If false (default value), the author styles are not applied to the shadow DOM subtree. If true, the author styles are applied.
host of type Element, readonly: refers back to the shadow host. This value is never null.
innerHTML of type DOMString: represents the markup of ShadowRoot's contents, and operates as specified, given ShadowRoot as the context object.

708 | 709 |

The nodeType attribute of a ShadowRoot instance must return DOCUMENT_FRAGMENT_NODE. Accordingly, the nodeName attribute of a ShadowRoot instance must return "#document-fragment".

710 | 711 |

`ShadowRoot` Methods

712 | 713 |

constructor

716 | Creates new shadow root and associates it with the shadow host. 717 | 718 | 719 | 720 | 721 | 722 | 723 | 724 | 725 | 726 | 727 | 728 | 729 | 730 | 731 | 732 | 733 | 734 | 735 | 736 |

Parameter	Type	Nullable	Optional	Description
`element`	`Element`	No	No	Element that will be hosting this instance of the shadow DOM subtree.

737 |

738 | Exceptions: 739 |

HIERARCHY_REQUEST_ERR: Thrown when the element parameter is not a valid Element. 742 |

743 |

744 |

745 | Returns: a new ShadowRoot instance. 746 |

747 |

getElementById

Behaves exactly like document.getElementById, except scoped to the shadow DOM subtree.

getElementsByClassName

Behaves exactly like document.getElementsByClassName, except scoped to the shadow DOM subtree.

getElementsByTagName

Behaves exactly like document.getElementsByTagName, except scoped to the shadow DOM subtree.

getElementsByTagNameNS

Behaves exactly like document.getElementsByTagNameNS, except scoped to the shadow DOM subtree.

757 | 758 |

Invoking the cloneNode() method on a ShadowRoot instance must always throw a DATA_CLONE_ERR exception.

759 | 760 | 761 |

The `content` element

762 | 763 |

The content element represents an insertion point in the shadow DOM subtree.

764 | 765 |

Context

Where flow content is expected.

Content model

Transparent

Children

Anything as fallback content

Content attributes

Global attributes

775 |

select, a set of comma-separated tokens: 780 | defines the matching criteria for distributing child nodes of the host element. Each token must be a valid selector fragment. If any token is invalid, the entire value of the select attribute is considered invalid. 781 |

783 |

DOM Interface

786 |


787 | interface HTMLContentElement : HTMLElement {
788 |     attribute DOMString select;
789 | }
790 |

791 |

Attributes

802 | 803 | 804 | 805 | 806 |

The `shadow` element

807 | 808 |

The shadow element represents an shadow insertion point in a shadow DOM subtree.

809 | 810 |

Context

Where flow content is expected.

Content model

Transparent

Children

Anything as fallback content

Content attributes

Global attributes

DOM Interface

821 |


822 | interface HTMLShadowElement : HTMLElement {
823 | }
824 |

825 |

826 | 827 | 828 |

Shadow DOM Example

829 | 830 |

Bob was asked to turn a simple list of links into a News Widget, which has links organized into two categories: breaking news and just news. The current document markup for the stories looks like this:

831 |


832 | <ul class="stories">
833 |     <li><a href="//example.com/stories/1">A story</a></li>
834 |     <li><a href="//example.com/stories/2">Another story</a></li>
835 |     <li class="breaking"><a href="//example.com/stories/3">Also a story</a></li>
836 |     <li><a href="//example.com/stories/4">Yet another story</a></li>
837 |     <li><a href="//example.com/stories/4">Awesome story</a></li>
838 |     <li class="breaking"><a href="//example.com/stories/5">Horrible story</a></li>
839 | </ul>
840 |

841 | 842 |

To organize the stories, Bob decides to use shadow DOM. Doing so will allow Bob to keep the document markup uncluttered, and harnessing the power of insertion point makes sorting stories by class name a very simple task. After getting another cup of Green Eye, he quickly mocks up the following shadow DOM subtree, to be hosted by the ul element:

843 |


844 | <div class="breaking">
845 |     <ul>
846 |         <content select=".breaking"></content> <!-- insertion point for breaking news -->
847 |     </ul>
848 | </div>
849 | <div class="other">
850 |     <ul>
851 |         <content></content> <!-- insertion point for the rest of the news -->
852 |     </ul>
853 | </div>
854 |

855 |

Bob then styles the newborn widget according to comps from the designer by adding this to the shadow DOM subtree mockup:

856 |


857 | <style scoped>
858 |     div.breaking {
859 |         color: Red;
860 |         font-size: 20px;
861 |         border: 1px dashed Purple;
862 |     }
863 |     div.other {
864 |         padding: 2px 0 0 0;
865 |         border: 1px solid Cyan;
866 |     }
867 | </style>
868 |

869 |

While pondering if his company should start looking for a new designer, Bob converts the mockup to code:

870 |


871 | function createStoryGroup(className, contentSelector)
872 | {
873 |     var group = document.createElement('div');
874 |     group.className = className;
875 |     // Empty string in select attribute or absence thereof work the same, so no need for special handling.
876 |     group.innerHTML = '<ul><content select="' + contentSelector + '"></content></ul>';
877 |     return group;
878 | }
879 | 
880 | function createStyle()
881 | {
882 |     var style = document.createElement('style');
883 |     style.scoped = true;
884 |     style.textContent = 'div.breaking { color: Red;font-size: 20px; border: 1px dashed Purple; }' +
885 |         'div.other { padding: 2px 0 0 0; border: 1px solid Cyan; }';
886 |     return style;
887 | }
888 | 
889 | function makeShadowSubtree(storyList)
890 | {
891 |     var root = new ShadowRoot(storyList);
892 |     root.appendChild(createStyle());
893 |     root.appendChild(createStoryGroup('breaking', '.breaking'));
894 |     root.appendChild(createStoryGroup('other', ''));
895 | }
896 | 
897 | document.addEventListener('DOMContentLoaded', function {
898 |     [].forEach.call(document.querySelectorAll('ul.stories'), makeShadowSubtree);
899 | });
900 |

901 | 902 |

Well done, Bob! With the cup of coffee still half-full, the work is complete. Recognizing his awesomeness, Bob returns to teaching n00bs the ways of WoW.

903 | 904 |

A few months pass.

905 | 906 |

It's election time. With Bob at his annual conference, Alice is charged with adding another, temporary box to the news widget, filled with election-related stories. Alice studies Bob's code, reads up on the shadow DOM spec and realizes that, thanks to multiple shadow DOM subtree support, she doesn't have to touch his code. As usual, her solution is elegant and simple, fitting neatly right under Bob's code:

907 |


908 | // TODO(alice): BEGIN -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.
909 | var ELECTION_BOX_REMOVAL_DEADLINE = ...;
910 | 
911 | function createElectionStyle()
912 | {
913 |     var style = document.createElement('style');
914 |     style.scoped = true;
915 |     // TODO(alice): Check designer's desk for hallucinogens.
916 |     style.textContent = 'div.election { color: Magenta;font-size: 24px; border: 2px dotted Fuchsia; }';
917 |     return style;
918 | }
919 | 
920 | function makeElectionShadowSubtree(storyList)
921 | {
922 |     var root = new ShadowRoot(storyList);
923 |     // Add and style election story box.
924 |     root.appendChild(createElectionStyle());
925 |     root.appendChild(createStoryGroup('election', '.election'));
926 |     // Insert Bob's shadow tree under the election story box.
927 |     root.appendChild(document.createElement('shadow'));
928 | }
929 | 
930 | if (Date.now() < ELECTION_BOX_REMOVAL_DEADLINE) {
931 |     document.addEventListener('DOMContentLoaded', function {
932 |         [].forEach.call(document.querySelectorAll('ul.stories'), makeElectionShadowSubtree);
933 |     });
934 | }
935 | // TODO(alice): END -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.
936 |

937 |

Using the shadow element allows Alice to compose Bob's widget inside of hers—without having to change a line of production code. Smiling to herself, Alice realizes that Bob may have come up with a way to keep the document markup clean, but she is the one who takes the cake for using shadow DOM subtree composition in such a cool way.

938 | 939 |

940 |

Acknowledgements

941 |

942 |

David Hyatt developed XBL 1.0, and Ian Hickson co-wrote XBL 2.0. These documents provided tremendous insight into the problem of functional encapsulation and greatly influenced this specification.

943 | 944 |

Alex Russell and his considerable forethought triggered a new wave of enthusiasm around the subject of shadow DOM and how it can be applied practically on the Web.

945 | 946 |

Dominic Cooney, Hajime Morrita, and Roland Steiner worked tirelessly to scope the problem of functional encapsulation within the confines of the Web platform and provided a solid foundation for this document.

947 | 948 |

The editor would also like to thank Alex Komoroske, Brian Kardell, Darin Fisher, Edward O'Connor, Elisée Maurer, Erik Arvidsson, Hayato Ito, Jonas Sicking, Malte Ubl, Olli Pettay, Rafael Weinstein, Sam Dutton, and Tab Atkins for their comments and contributions to this specification.

949 | 950 |

This list is too short. There's a lot of work left to do. Please contribute by reviewing and filing bugs—and don't forget to ask the editor to add your name into this section.

951 |

952 | 953 |

Accordion Component Example

About Us

Services

Blog

Portfolio

Contact

Simple Web Components Example

Breaking Stories

Other News

Tabs