1. 6.11 The popover attribute
      1. 6.11.1 The popover target attributes
      2. 6.11.2 Popover light dismiss
      3. 6.11.3 The BeforeToggleEvent interface

6.11 The popover attribute

All HTML elements may have the popover content attribute set. When specified, the element won't be rendered until it becomes shown, at which point it will be rendered on top of other page content.

The popover attribute is an enumerated attribute. The following table lists the states for this attribute:

StateKeywordsDescription
Auto stateautoCloses other popovers when opened; has light dismiss.
The empty string
Manual statemanualDoes not close other popovers; does not light dismiss.

The attribute may be omitted. The invalid value default is the manual state. The missing value default is the no popover state.

The popover IDL attribute must reflect the popover attribute, limited to only known values.

Every HTML element has a popover visibility state, initially hidden, with these potential values:

The Document has an auto popover list, which is a list, initially empty.

The Document has a popover pointerdown target, which is an HTML element or null, initially null.

Every HTML element has a popover invoker, which is an HTML element or null, initially set to null.

The following attribute change steps are used for all HTML elements:

  1. If namespace is not null, then return.

  2. If localName is not popover, then return.

  3. If oldValue and value are in different states, then run the hide popover algorithm given element, true, false, and false.

element.showPopover()
Shows the popover element by adding it to the top layer. If element's popover attribute is in the auto state, then this will also close all other auto popovers unless they are an ancestor of element according to the topmost popover ancestor algorithm.
element.hidePopover()
Hides the popover element by removing it from the top layer and applying display: none to it.
element.togglePopover()
If the popover element is not showing, then this method shows it. Otherwise, this method hides it.

The showPopover() method steps are:

  1. Run show popover given this and true.

To show popover, given an HTML element element and a boolean throwExceptions:

  1. If the result of running check popover validity given element and false is false, then:

    1. Assert: throwExceptions is true.

    2. Throw an "InvalidStateError" DOMException.

  2. Assert: element is not in element's node document's top layer.

  3. If the result of firing an event named beforetoggle, using BeforeToggleEvent, with the cancelable attribute initialized to true, the currentState attribute initialized to "closed", and the newState attribute initialized to "open" at element is false, then return.

  4. If the result of running check popover validity given element and false is false:

    1. If throwExceptions is true, then throw an "InvalidStateError" DOMException.

    2. Otherwise, return.

    Check popover validity is called again because firing the beforetoggle event could have disconnected this element or changed its popover attribute.

  5. Let document be element's node document.

  6. Let shouldRestoreFocus be false.

  7. If element's popover attribute is in the auto state, then:

    1. Let originalType be the value of element's popover attribute.

    2. Let ancestor be the result of running the topmost popover ancestor algorithm given element.

    3. Run hide all popovers until given ancestor, false, and false.

    4. If originalType is not equal to the value of element's popover attribute, or if the result of running check popover validity given element and false is false:

      1. If throwExceptions is true, then throw an "InvalidStateError" DOMException.

      2. Otherwise, return.

      Check popover validity is called again because running hide all popovers until above could have fired the beforetoggle event, and an event handler could have disconnected this element or called showPopover() on this element.

  8. If the result of running topmost auto popover on document is null, then set shouldRestoreFocus to true.

    This ensures that focus is returned to the previously-focused element only for the first popover in a stack.

  9. Add element to document's auto popover list.

  10. Set element's previously focused element to null.

  11. Let originallyFocusedElement be document's focused area of the document's DOM anchor.

  12. Add element to document's top layer.

  13. Set element's popover visibility state to showing.

  14. Run the popover focusing steps given element.

  15. If shouldRestoreFocus is true and element's popover attribute is not in the no popover state, then set element's previously focused element to originallyFocusedElement.

The hidePopover() method steps are:

  1. Run the hide popover algorithm given this, true, false, and true.

To hide a popover given an HTML element element, a boolean focusPreviousElement, a boolean dontFireBeforetoggle, and a boolean throwExceptions:

  1. If the result of running check popover validity given element and true is false:

    1. If throwExceptions is true, then throw an "InvalidStateError" DOMException.

    2. Otherwise, return.

  2. Let document be element's node document.

  3. If element's popover attribute is in the auto state, then:

    1. Run hide all popovers until given element, focusPreviousElement, and dontFireBeforetoggle.

    2. If element is not in document's auto popover list:

      1. If throwExceptions is true, then throw an "InvalidStateError" DOMException.

      2. Otherwise, return.

    3. Assert: The last item in document's auto popover list is element.

    4. Remove element from document's auto popover list.

  4. Set element's popover invoker to null.

  5. If dontFireBeforetoggle is false:

    1. Fire an event named beforetoggle, using BeforeToggleEvent, with the cancelable attribute initialized to false, the currentState attribute initialized to "open", and the newState attribute initialized to "closed" at element.

    2. If the result of running check popover validity given element and true is false:

      1. If throwExceptions is true, then throw an "InvalidStateError" DOMException.

      2. Otherwise, return.

      Check popover validity is called again because firing the beforetoggle event could have disconnected this element or changed its popover attribute.

  6. Remove element from the top layer.

  7. Set element's popover visibility state to hidden.

  8. Let previouslyFocusedElement be element's previously focused element.

  9. If previouslyFocusedElement is not null, then:

    1. Set element's previously focused element to null.

    2. If focusPreviousElement is true, then run the focusing steps for previouslyFocusedElement; the viewport should not be scrolled by doing this step.

The togglePopover(force) method steps are:

  1. If this's popover attribute is in the no popover state, then throw a "NotSupportedError" DOMException.

  2. If this is not connected, then throw a "InvalidStateError" DOMException.

  3. If this's popover visibility state is showing, and force is not present or false, then run the hide popover algorithm given this, true, false, and true.

  4. Otherwise, if force is not present or true, then run show popover given this and true.

To hide all popovers until, given an HTML element endpoint, a boolean focusPreviousElement, and a boolean dontFireBeforetoggle:

  1. Let document be endpoint's node document.

  2. Let closeAllOpenPopovers be an algorithm which performs the following steps:

    1. Let popover be document's topmost auto popover.

    2. While popover is not null:

      1. Run the hide popover algorithm given popover, focusPreviousElement, dontFireBeforetoggle, and false.

      2. Set popover to document's topmost auto popover.

  3. If endpoint is null, then run closeAllOpenPopovers and return.

  4. Let lastToHide be null.

  5. Let foundEndpoint be false.

  6. For each popover in document's auto popover list:

    1. If popover is endpoint, then set foundEndpoint to true.

    2. Otherwise, if foundEndpoint is true, then set lastToHide to popover and break.

  7. If foundEndpoint is false, then run closeAllOpenPopovers and return.

  8. While lastToHide is not null and lastToHide's popover visibility state is showing and document's auto popover list is not empty:

    1. Run the hide popover algorithm given document's auto popover list's last element, focusPreviousElement, dontFireBeforetoggle, and false.

The hide all popovers until algorithm is used in several cases to hide all popovers that don't stay open when something happens. For example, during light-dismiss of a popover, this algorithm ensures that we close only the popovers that aren't related to the node clicked by the user.

To find the topmost popover ancestor, given a Node newPopover, perform the following steps. They return an HTML element or null.

The topmost popover ancestor algorithm will return the topmost (highest in the auto popover list) ancestor popover for the provided popover. Popovers can be related to each other in several ways, creating a tree of popovers. There are two paths through which one popover (call it the "child" popover) can have an ancestor popover (call it the "parent" popover):

  1. The popovers are nested within each other in the DOM tree. In this case, the descendant popover is the "child" and its ancestor popover is the "parent".

  2. An invoking element (e.g. a button) has one of the invoking attributes (e.g. popovertoggletarget) pointing to a popover. In this case, the popover is the "child", and the DOM-contained popover of the invoking element is the "parent". The invoker must be in a popover and reference an open popover.

In each of the relationships formed above, the parent popover must be strictly lower in the auto popover list than the child popover, or it does not form a valid ancestral relationship. This eliminates non-showing popovers and self-pointers (e.g. a popover with an anchor attribute that points back to the same popover), and it allows for the construction of a well-formed tree from the (possibly cyclic) graph of connections. For example, if two popovers have anchors pointing to each other, the only valid relationship is that the first one to open is the "parent" and the second is the "child". Only auto popovers are considered.

  1. Let popoverPositions be an empty map.

  2. Let index be 0.

  3. Let document be newPopover's node document.

  4. For each popover in document's auto popover list:

    1. Set popoverPositions[popover] to index.

    2. Increment index by 1.

  5. Set popoverPositions[newPopover] to index.

  6. Increment index by 1.

  7. Let topmostPopoverAncestor be null.

  8. Let checkAncestor be an algorithm which performs the following steps given candidate:

    1. If candidate is null, then return.

    2. Let candidateAncestor be the result of running nearest inclusive open popover given candidate.

    3. If candidateAncestor is null, then return.

    4. Let candidatePosition be popoverPositions[candidateAncestor].

    5. If topmostPopoverAncestor is null or popoverPositions[topmostPopoverAncestor] is less than candidatePosition, then set topmostPopoverAncestor to candidateAncestor.

  9. Run checkAncestor given the result of running nearest inclusive open popover given newPopover's parent node within the flat tree.

  10. For each invoker in document's popover invokers:

    1. If invoker's popover target element is newPopover, then run checkAncestor given invoker.

  11. return topmostPopoverAncestor.

To find the nearest inclusive open popover given a Node node, perform the following steps. They return an HTML element or null.

  1. Let currentNode be node.

  2. While currentNode is not null:

    1. If currentNode's popover attribute is in the auto state and currentNode's popover visibility state is showing, then return currentNode.

    2. Set currentNode to currentNode's parent in the flat tree.

  3. Return null.

To find the topmost auto popover given a Document document, perform the following steps. They return an HTML element or null.

  1. If document's auto popover list is not empty, then return document's auto popover list's last element.

  2. Return null.

To perform the popover focusing steps for an HTML element subject:

  1. Let control be the focus delegate of subject given "other" and true.

  2. If control is null, then return.

  3. Run the focusing steps given control.

  4. Let topDocument be the active document of control's node document's browsing context's top-level browsing context.

  5. If control's node document's origin is not the same as the origin of topDocument, then return.

  6. Empty topDocument's autofocus candidates.

  7. Set topDocument's autofocus processed flag to true.

To check popover validity for an HTML element element given a boolean expectedToBeShowing, perform the following steps. They return a boolean.

  1. If element's popover attribute is in the no popover state, then return false.

  2. If element is not connected, then return false.

  3. If expectedToBeShowing is true and element's popover visibility state is not showing, then return false.

  4. If expectedToBeShowing is false and element's popover visibility state is not hidden, then return false.

  5. If element is a dialog element and has the open attribute, then return false.

  6. If element's fullscreen flag is set, then return false.

  7. Return true.

6.11.1 The popover target attributes

Supported elements may have the following content attributes, known as the popover target attributes:

The popover target attributes allow certain types of buttons to show and hide element with the popover attribute. If a popover target attribute is specified, then that attribute's value must be the ID of element with the popover attribute.

The following shows how popovershowtarget can be used to open a popover:

<div popover=auto id="foo">
  This is a popover!
</div>

<button popovershowtarget="foo">
  Show a popover
</button>

The following shows how popovertoggletarget can open and close a manual popover, which can't be closed with light dismiss:

<div popover=manual id="foo">
  This is a popover!
</div>

<button popovertoggletarget="foo">
  Show or hide a popover
</button>

The popover target attributes are only supported on the following elements:

DOM interface: 
interface mixin PopoverTargetElement {
  [CEReactions] attribute Element? popoverToggleTargetElement;
  [CEReactions] attribute Element? popoverHideTargetElement;
  [CEReactions] attribute Element? popoverShowTargetElement;
};

The popoverToggleTargetElement IDL attribute must reflect the popovertoggletarget attribute.

The popoverHideTargetElement IDL attribute must reflect the popoverhidetarget attribute.

The popoverShowTargetElement IDL attribute must reflect the popovershowtarget attribute.

To run the popover target attribute activation behavior given a Node node:

  1. Let popover be node's popover target element.

  2. If popover is null, then return.

  3. If node doesn't have the popovertoggletarget attribute, then:

    1. If node has a popovershowtarget attribute and popover's popover visibility state is showing, then return.

    2. If node has a popoverhidetarget attribute and popover's popover visibility state is hidden, then return.

  4. If popover's popover visibility state is showing, then run the hide popover algorithm given popover, true, false, and false.

  5. Otherwise:

    1. Set popover's popover invoker to node.

    2. Run show popover given popover and false.

To get the popover target element given a Node node, perform the following steps. They return an HTML element or null.

  1. If node is not supported, then return null.

  2. If node is disabled, then return null.

  3. If node has a form owner and node is a submit button, then return null.

  4. Let idref be null.

  5. If node has a popovertoggletarget attribute, then set idref to the value of node's popovertoggletarget attribute.

  6. Otherwise, if node has a popovershowtarget attribute, then set idref to the value of node's popovershowtarget attribute.

  7. Otherwise, if node has a popoverhidetarget attribute, then set idref to the value of node's popoverhidetarget attribute.

  8. If idref is null, then return null.

  9. Let popoverElement be the first element in tree order, within node's root's descendants, whose ID is idref; otherwise, if there is no such element, null.

  10. If popoverElement is null, then return null.

  11. If popoverElement's popover attribute is in the no popover state, then return null.

  12. Return popoverElement.

To get the popover invokers given a Document document:

  1. Return an HTMLCollection rooted at document whose filter matches elements which support the popover target attributes.

6.11.2 Popover light dismiss

"Light dismiss" means that pressing the Esc key or clicking outside of a popover whose popover attribute is in the auto state will close the popover.

Canceling popovers: When Document has a topmost auto popover showing, user agents may provide a user interface that, upon activation, queues an element task on the user interaction task source given topmost auto popover to run the hide popover algorithm given the topmost auto popover, true, and false.

To light dismiss open popovers, given an Event event and a Node node:

  1. Assert: event's isTrusted attribute is true.

  2. Let topmostPopover be the result of running topmost auto popover given node.

  3. If topmostPopover is null, then return.

  4. Let target be event's target.

  5. Let document be node's node document.

  6. If event is a PointerEvent and event's type is pointerdown, then:

    1. Set document's popover pointerdown target to the result of running topmost clicked popover given target and "inclusive".

  7. If event is a PointerEvent and event's type is pointerup, then:

    1. Let ancestor be the result of running topmost clicked popover given target.

    2. Let sameTarget be true if ancestor is document's popover pointerdown target.

    3. Set document's popover pointerdown target to null.

    4. If sameTarget is true, then run hide all popovers until given ancestor, false, and false.

Light dismiss open popovers is called by the Pointer Events spec when the user clicks or touches anywhere on the page.

To find the topmost clicked popover, given a Node node:

  1. Let clickedPopover be the result of running nearest inclusive open popover given node.

  2. Let invokerPopover be the result of running nearest inclusive target popover for invoker given node.

  3. Let getStackPosition be an algorithm which performs the following steps given an HTML element popover:

    1. Let popoverList be popover's node document's auto popover list.

    2. If popover is in popoverList, then return the index of popover in popoverList + 1.

    3. Return 0.

  4. If the result of running getStackPosition given clickedPopover is greater than the result of running getStackPosition given invokerPopover, then return clickedPopover.

  5. Return invokerPopover.

To find the nearest inclusive target popover for invoker given a Node node:

  1. Let currentNode be node.

  2. While currentNode is not null:

    1. Let targetPopover be currentNode's popover target element.

    2. If targetPopover is not null and targetPopover's popover attribute is in the auto state and targetPopover's popover visibility state is showing, then return targetPopover.

    3. Set currentNode to currentNode's ancestor in the flat tree.

6.11.3 The BeforeToggleEvent interface

[Exposed=Window]
interface BeforeToggleEvent : Event {
  constructor(DOMString type, optional BeforeToggleEventInit eventInitDict = {});
  readonly attribute DOMString currentState;
  readonly attribute DOMString newState;
};

dictionary BeforeToggleEventInit : EventInit {
  DOMString currentState = "";
  DOMString newState = "";
};
event.currentState

Set to "closed" when transitioning from closed to open, or set to "open" when transitioning from open to closed.

event.newState

Set to "open" when transitioning from closed to open, or set to "closed" when transitioning from open to closed.

The currentState attribute must return the value it was initialized to. It is initialized to "open" if the element with the popover attribute's popover visibility state is showing, otherwise "closed".

The newState attribute must return the value it was initialized to. It is initialized to "closed" if the element with the popover attribute's popover visibility state is showing, otherwise "open".