HTML

Living Standard — Last Updated 30 April 2025

1. 1. 6.12 The popover attribute
      1. 6.12.1 The popover target attributes
      2. 6.12.2 Popover light dismiss

6.12 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.

<ul>
  <li>
    <a href=...>All Products</a>
    <button popovertarget=sub-nav>
     <img src=down-arrow.png alt="Product pages">
    </button>
    <ul popover id=sub-nav>
     <li><a href=...>Shirts</a>
     <li><a href=...>Shoes</a>
     <li><a href=...>Hats etc.</a>
    </ul>
  </li>
  <!-- other list items and links here -->
</ul>

When using popover on elements without accessibility semantics, for instance the div element, authors should use the appropriate ARIA attributes to ensure the popover is accessible.

<button popovertarget=m>Actions</button>
<div role=menu id=m popover>
  <button role=menuitem tabindex=-1 autofocus>Edit</button>
  <button role=menuitem tabindex=-1>Hide</button>
  <button role=menuitem tabindex=-1>Delete</button>
</div>

<button id=submit>Submit</button>
<p><output><span popover=manual></span></output></p>

<script>
 const sBtn = document.getElementById("submit");
 const outSpan = document.querySelector("output [popover=manual]");
 let successMessage;
 let errorMessage;

 /* define logic for determining success of action
  and determining the appropriate success or error
  messages to use */

 sBtn.addEventListener("click", ()=> {
  if ( success ) {
   outSpan.textContent = successMessage;
  }
  else {
   outSpan.textContent = errorMessage;
  }
  outSpan.showPopover();

  setTimeout(function () {
   outSpan.hidePopover();
  }, 10000);
 });
</script>

Inserting a popover element into an output element will generally cause screen readers to announce the content when it becomes visible. Depending on the complexity or frequency of the content, this could be either useful or annoying to users of these assistive technologies. Keep this in mind when using the output element or other ARIA live regions to ensure the best user experience.

The popover attribute is an enumerated attribute with the following keywords and states:

The attribute's missing value default is the no popover state, and its invalid value default is the manual 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:

• hidden

• showing

Every 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.

Every HTML element has a popover showing or hiding, which is a boolean, initially set to false.

Every HTML element popover toggle task tracker, which is a toggle task tracker or null, initially null.

Every HTML element has a popover close watcher, which is a close watcher or null, initially null.

Every HTML element has an opened in popover mode, which is a string or null, initially null.

The following attribute change steps, given element, localName, oldValue, value, and namespace, are used for all HTML elements:

1. If namespace is not null, then return.

2. If localName is not popover, then return.

3. If element's popover visibility state is in the showing state and oldValue and value are in different states, then run the hide popover algorithm given element, true, true, 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. This method returns true if the popover is open after calling it, otherwise false.

The showPopover(options) method steps are:

1. Let invoker be options["source"] if it exists; otherwise, null.

2. Run show popover given this, true, and invoker.

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

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

2. Let document be element's node document.

3. Assert: element's popover invoker is null.

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

5. Let nestedShow be element's popover showing or hiding.

6. Let fireEvents be the boolean negation of nestedShow.

7. Set element's popover showing or hiding to true.

8. Let cleanupShowingFlag be the following steps:

   1. If nestedShow is false, then set element's popover showing or hiding to false.

9. If the result of firing an event named beforetoggle, using ToggleEvent, with the cancelable attribute initialized to true, the oldState attribute initialized to "closed", and the newState attribute initialized to "open" at element is false, then run cleanupShowingFlag and return.

10. If the result of running check popover validity given element, false, throwExceptions, and document is false, then run cleanupShowingFlag and return.

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

11. Let shouldRestoreFocus be false.

12. Let originalType be the current state of element's popover attribute.

13. Let stackToAppendTo be null.

14. Let autoAncestor be the result of running the topmost popover ancestor algorithm given element, document's showing auto popover list, invoker, and true.

15. Let hintAncestor be the result of running the topmost popover ancestor algorithm given element, document's showing hint popover list, invoker, and true.

16. If originalType is the auto state, then:

    1. Run close entire popover list given document's showing hint popover list, shouldRestoreFocus, and fireEvents.

    2. Let ancestor be the result of running the topmost popover ancestor algorithm given element, document's showing auto popover list, invoker, and true.

    3. If ancestor is null, then set ancestor to document.

    4. Run hide all popovers until given ancestor, shouldRestoreFocus, and fireEvents.

    5. Set stackToAppendTo to "auto".

17. If originalType is the hint state, then:

    1. If hintAncestor is not null, then:

       1. Run hide all popovers until given hintAncestor, shouldRestoreFocus, and fireEvents.

       2. Set stackToAppendTo to "hint".

    2. Otherwise:

       1. Run close entire popover list given document's showing hint popover list, shouldRestoreFocus, and fireEvents.

       2. If autoAncestor is not null, then:

          1. Run hide all popovers until given autoAncestor, shouldRestoreFocus, and fireEvents.

          2. Set stackToAppendTo to "auto".

       3. Otherwise, set stackToAppendTo to "hint".

18. If originalType is auto or hint, then:

    1. Assert: stackToAppendTo is not null.

    2. If originalType is not equal to the value of element's popover attribute, then:

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

       2. Return.

    3. If the result of running check popover validity given element, false, throwExceptions, and document is false, then run cleanupShowingFlag and 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 changed its popover attribute.

    4. If the result of running topmost auto or hint 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.

    5. If stackToAppendTo is "auto":

       1. Assert: document's showing auto popover list does not contain element.

       2. Set element's opened in popover mode to "auto".

       Otherwise:

       1. Assert: stackToAppendTo is "hint".

       2. Assert: document's showing hint popover list does not contain element.

       3. Set element's opened in popover mode to "hint".

    6. Set element's popover close watcher to the result of establishing a close watcher given element's relevant global object, with:

       • cancelAction being to return true.

       • closeAction being to hide a popover given element, true, true, and false.

       • getEnabledState being to return true.

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

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

21. Add an element to the top layer given element.

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

23. Set element's popover invoker to invoker.

24. Set element's implicit anchor element to invoker.

25. Run the popover focusing steps given element.

26. 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.

27. Queue a popover toggle event task given element, "closed", and "open".

28. Run cleanupShowingFlag.

To queue a popover toggle event task given an element element, a string oldState, and a string newState:

1. If element's popover toggle task tracker is not null, then:

   1. Set oldState to element's popover toggle task tracker's old state.

   2. Remove element's popover toggle task tracker's task from its task queue.

   3. Set element's popover toggle task tracker to null.

2. Queue an element task given the DOM manipulation task source and element to run the following steps:

   1. Fire an event named toggle at element, using ToggleEvent, with the oldState attribute initialized to oldState and the newState attribute initialized to newState.

   2. Set element's popover toggle task tracker to null.

3. Set element's popover toggle task tracker to a struct with task set to the just-queued task and old state set to oldState.

The hidePopover() method steps are:

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

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

1. If the result of running check popover validity given element, true, throwExceptions, and null is false, then return.

2. Let document be element's node document.

3. Let nestedHide be element's popover showing or hiding.

4. Set element's popover showing or hiding to true.

5. If nestedHide is true, then set fireEvents to false.

6. Let cleanupSteps be the following steps:

   1. If nestedHide is false, then set element's popover showing or hiding to false.

   2. If element's popover close watcher is not null, then:

      1. Destroy element's popover close watcher.

      2. Set element's popover close watcher to null.

7. If element's opened in popover mode is "auto" or "hint", then:

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

   2. If the result of running check popover validity given element, true, and throwExceptions is false, then run cleanupSteps and return.

      Check popover validity is called again because running hide all popovers until could have disconnected element or changed its popover attribute.

8. Let autoPopoverListContainsElement be true if document's showing auto popover list's last item is element, otherwise false.

9. Set element's popover invoker to null.

10. If fireEvents is true:

    1. Fire an event named beforetoggle, using ToggleEvent, with the oldState attribute initialized to "open" and the newState attribute initialized to "closed" at element.

    2. If autoPopoverListContainsElement is true and document's showing auto popover list's last item is not element, then run hide all popovers until given element, focusPreviousElement, and false.

    3. If the result of running check popover validity given element, true, throwExceptions, and null is false, then run cleanupSteps and return.

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

    4. Request an element to be removed from the top layer given element.

    5. Set element's implicit anchor element to null.

11. Otherwise, remove an element from the top layer immediately given element.

12. Set element's opened in popover mode to null.

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

14. If fireEvents is true, then queue a popover toggle event task given element, "open", and "closed".

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

16. If previouslyFocusedElement is not null, then:

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

    2. If focusPreviousElement is true and document's focused area of the document's DOM anchor is a shadow-including inclusive descendant of element, then run the focusing steps for previouslyFocusedElement; the viewport should not be scrolled by doing this step.

17. Run cleanupSteps.

The togglePopover(options) method steps are:

1. Let force be null.

2. If options is a boolean, set force to options.

3. Otherwise, if options["force"] exists, set force to options["force"].

4. Let invoker be options["source"] if it exists; otherwise, null.

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

6. Otherwise, if force is null or true, then run show popover given this, true, and invoker.

7. Otherwise:

   1. Let expectedToBeShowing be true if this's popover visibility state is showing; otherwise false.

   2. Run check popover validity given expectedToBeShowing, true, and null.

8. Return true if this's popover visibility state is showing; otherwise false.

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

1. If endpoint is an HTML element and endpoint is not in the popover showing state, then return.

2. Let document be endpoint's node document.

3. Assert: endpoint is a Document or endpoint's popover visibility state is showing.

4. Assert: endpoint is a Document or endpoint's popover attribute is in the auto state or endpoint's popover attribute is in the hint state.

5. If endpoint is a Document:

   1. Run close entire popover list given document's showing hint popover list, focusPreviousElement, and fireEvents.

   2. Run close entire popover list given document's showing auto popover list, focusPreviousElement, and fireEvents.

   3. Return.

6. If document's showing hint popover list contains endpoint:

   1. Assert: endpoint's popover attribute is in the hint state.

   2. Run hide popover stack until given endpoint, document's showing hint popover list, focusPreviousElement, and fireEvents.

   3. Return.

7. Run close entire popover list given document's showing hint popover list, focusPreviousElement, and fireEvents.

8. If document's showing auto popover list does not contain endpoint, then return.

9. Run hide popover stack until given endpoint, document's showing auto popover list, focusPreviousElement, and fireEvents.

To hide popover stack until, given an HTML element endpoint, a list popoverList, a boolean focusPreviousElement, and a boolean fireEvents:

1. Let repeatingHide be false.

2. Perform the following steps at least once:

   1. Let lastToHide be null.

   2. For each popover in popoverList:

      1. If popover is endpoint, then break.

      2. Set lastToHide to popover.

   3. If lastToHide is null, then return.

   4. While lastToHide's popover visibility state is showing:

      1. Assert: popoverList is not empty.

      2. Run the hide popover algorithm given the last item in popoverList, focusPreviousElement, fireEvents, and false.

   5. Assert: repeatingHide is false or popoverList's last item is endpoint.

   6. Set repeatingHide to true if popoverList contains endpoint and popoverList's last item is not endpoint, otherwise false.

   7. If repeatingHide is true, then set fireEvents to false.

   and keep performing them while repeatingHide is true.

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 newPopoverOrTopLayerElement, a list popoverList, an HTML element or null invoker, and a boolean isPopover, perform the following steps. They return an HTML element or null.

1. If isPopover is true:

   1. Assert: newPopoverOrTopLayerElement is an HTML element.

   2. Assert: newPopoverOrTopLayerElement's popover attribute is not in the no popover state or the manual state.

   3. Assert: newPopoverOrTopLayerElement's popover visibility state is not in the popover showing state.

2. Otherwise:

   1. Assert: invoker is null.

3. Let popoverPositions be an empty ordered map.

4. Let index be 0.

5. For each popover of popoverList:

   1. Set popoverPositions[popover] to index.

   2. Increment index by 1.

6. If isPopover is true, then set popoverPositions[newPopoverOrTopLayerElement] to index.

7. Increment index by 1.

8. Let topmostPopoverAncestor be null.

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

   1. If candidate is null, then return.

   2. Let okNesting be false.

   3. Let candidateAncestor be null.

   4. While okNesting is false:

      1. Set candidateAncestor to the result of running nearest inclusive open popover given candidate.

      2. If candidateAncestor is null or popoverPositions does not contain candidateAncestor, then return.

      3. Assert: candidateAncestor's popover attribute is not in the manual or none state.

      4. Set okNesting to true if newPopoverOrTopLayerElement's popover attribute is in the hint state or candidateAncestor's popover attribute is in the auto state.

      5. If okNesting is false, then set candidate to candidateAncestor's parent in the flat tree.

   5. Let candidatePosition be popoverPositions[candidateAncestor].

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

10. Run checkAncestor given newPopoverOrTopLayerElement's parent node within the flat tree.

11. Run checkAncestor given invoker.

12. 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 or hint popover given a Document document, perform the following steps. They return an HTML element or null.

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

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

3. Return null.

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

1. If the allow focus steps given subject's node document return false, then return.

2. If subject is a dialog element, then run the dialog focusing steps given subject and return.

3. If subject has the autofocus attribute, then let control be subject.

4. Otherwise, let control be the autofocus delegate for subject given "other".

5. If control is null, then return.

6. Run the focusing steps given control.

7. Let topDocument be control's node navigable's top-level traversable's active document.

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

9. Empty topDocument's autofocus candidates.

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

To check popover validity for an HTML element element given a boolean expectedToBeShowing, a boolean throwExceptions, and a Document or null expectedDocument, perform the following steps. They throw an exception or return a boolean.

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

   1. If throwExceptions is true, then throw a "NotSupportedError" DOMException.

   2. Return false.

2. If any of the following are true:

   • expectedToBeShowing is true and element's popover visibility state is not showing; or

   • expectedToBeShowing is false and element's popover visibility state is not hidden,

   then return false.

3. If any of the following are true:

   • element is not connected;

   • element's node document is not fully active;

   • expectedDocument is not null and element's node document is not expectedDocument;

   • element is a dialog element and its is modal is set to true; or

   • element's fullscreen flag is set,

   then:

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

   2. Return false.

4. Return true.

To get the showing auto popover list for a Document document:

1. Let popovers be « ».

2. For each Element element in document's top layer:

   1. If all of the following are true:

      • element is an HTML element;

      • element's opened in popover mode is "auto"; and

      • element's popover visibility state is showing,

      then append element to popovers.

3. Return popovers.

To get the showing hint popover list for a Document document:

1. Let popovers be « ».

2. For each Element element in document's top layer:

   1. If all of the following are true:

      • element is an HTML element;

      • element's opened in popover mode is "hint"; and

      • element's popover visibility state is showing,

      then append element to popovers.

3. Return popovers.

To close entire popover list given a list popoverList, a boolean focusPreviousElement, and a boolean fireEvents:

1. While popoverList is not empty:

   1. Run the hide popover algorithm given popoverList's last item, focusPreviousElement, fireEvents, and false.

6.12.1 The popover target attributes

Buttons may have the following content attributes:

• popovertarget

• popovertargetaction

If specified, the popovertarget attribute value must be the ID of an element with a popover attribute in the same tree as the button with the popovertarget attribute.

The popovertargetaction attribute is an enumerated attribute with the following keywords and states:

The attribute's missing value default and invalid value default are both the toggle state.

Whenever possible ensure the popover element is placed immediately after its triggering element in the DOM. Doing so will help ensure that the popover is exposed in a logical programmatic reading order for users of assistive technology, such as screen readers.

<button popovertarget="foo" popovertargetaction="show">
  Show a popover
</button>

<article popover="auto" id="foo">
  This is a popover article!
  <button popovertarget="foo" popovertargetaction="hide">Close</button>
</article>

<input type="button" popovertarget="foo" value="Toggle the popover">

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

interface mixin PopoverInvokerElement {
  [CEReactions] attribute Element? popoverTargetElement;
  [CEReactions] attribute DOMString popoverTargetAction;
};

The popoverTargetElement IDL attribute must reflect the popovertarget attribute.

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

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

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

2. If popover is null, then return.

3. If eventTarget is a shadow-including inclusive descendant of popover and popover is a shadow-including descendant of node, then return.

4. If node's popovertargetaction attribute is in the show state and popover's popover visibility state is showing, then return.

5. If node's popovertargetaction attribute is in the hide state and popover's popover visibility state is hidden, then return.

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

7. Otherwise, if popover's popover visibility state is hidden and the result of running check popover validity given popover, false, false, and null is true, then run show popover given popover, false, and node.

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 a button, 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 popoverElement be the result of running node's get the popovertarget-associated element.

5. If popoverElement is null, then return null.

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

7. Return popoverElement.

6.12.2 Popover light dismiss

"Light dismiss" means that clicking outside of a popover whose popover attribute is in the auto state will close the popover. This is in addition to how such popovers respond to close requests.

To light dismiss open popovers, given a PointerEvent event:

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

2. Let target be event's target.

3. Let document be target's node document.

4. Let topmostPopover be the result of running topmost auto popover given document.

5. If topmostPopover is null, then return.

6. If event's type is "pointerdown", then: set document's popover pointerdown target to the result of running topmost clicked popover given target.

7. If 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 ancestor is null, then set ancestor to document.

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

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. If the result of getting the popover stack position given clickedPopover is greater than the result of getting the popover stack position given invokerPopover, then return clickedPopover.

4. Return invokerPopover.

To get the popover stack position, given an HTML element popover:

1. Let hintList be popover's node document's showing hint popover list.

2. Let autoList be popover's node document's showing auto popover list.

3. If popover is in hintList, then return the index of popover in hintList + the size of autoList + 1.

4. If popover is in autoList, then return the index of popover in autoList + 1.

5. Return 0.

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.