1. 6.11 The popup attribute
      1. 6.11.1 The pop-up target attributes
      2. 6.11.2 Pop-up light dismiss
      3. 6.11.3 The defaultopen attribute
      4. 6.11.4 The anchor attribute

6.11 The popup attribute

All HTML elements may have the popup 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 popup attribute is an enumerated attribute. The following table lists the states for this attribute:

State Keywords Description
Auto state auto Closes other pop-ups when opened; has light dismiss.
The empty string
Manual state manual Does not close other pop-ups; does not light dismiss.

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

The attribute may be omitted. The invalid value default is the manual state. The missing value default is the no pop-up state.

Every HTML element has a pop-up visibility state, initially hidden, with these potential values:

The pop-up visibility transitioning state and :open pseudo selectors exist to allow pop-ups to animate open or closed because animating between display: none and other 'display' values is not possible.

The following is an example of an animated pop-up:

<div popup="auto" id="foo">
  A fancy pop-up with no Javascript
</div>
<style>
  [popup] {
    opacity: 0;
    transform: translate(-100px,100px);
    transition: all 1.5s;
  }
  [popup]:open {
    transform: translate(0,0);
    opacity: 1;
  }
</style>

The Document has an auto pop-up list, which is a list, initially empty.

The Document has pop-ups waiting to hide, which is a set, initially empty.

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

Every HTML element has the following members:

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

  1. If localName is not popup, then return.

  2. If oldValue is in the no pop-up state, then return.

  3. If value is not in the no pop-up state, then return.

  4. Run the hide pop-up algorithm given element, true, and false.

element.showPopUp()
Shows the pop-up element by adding it to the top layer. If element's popup attribute is in the auto state, then this will also close all other auto pop-ups unless they are an ancestor of element according to the nearest open ancestral pop-up algorithm.
element.hidePopUp()
Hides the pop-up element by removing it from the top layer and applying display: none to it.

The showPopUp() method steps are:

  1. Run show pop-up given this.

To show pop-up, given an HTML element element:

  1. Run check pop-up validity given element.

  2. If the result of firing an event named popupshow at element is false, then return.

  3. Run check pop-up validity given element.

    Check pop-up validity is called again because firing the popupshow event could have disconnected this element or changed its popup attribute.

  4. Let document be element's node document.

  5. Let shouldRestoreFocus be false.

  6. If element's popup attribute is in the auto state, then:

    1. Let ancestor be the result of running the nearest open ancestral pop-up algorithm given element and "new-pop-up".

    2. Run hide all pop-ups until given ancestor, false, and false.

  7. Run check pop-up validity given element.

    Check pop-up validity is called again because running hide all pop-ups until above could have fired the popuphide event, and an event handler could have disconnected this element or changed its popup attribute.

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

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

  9. Add element to document's auto pop-up list.

  10. Set element's waiting to hide pop-up to false.

  11. Set element's pop-up previously focused element to null.

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

  13. Add element to document's top layer.

  14. Set element's pop-up visibility state to transitioning.

  15. Recalculate styles and update layout for document.

  16. Set element's pop-up visibility state to showing.

  17. Run the pop-up focusing steps given element.

  18. If shouldRestoreFocus is true, element's popup attribute is not in the no pop-up state, and originallyFocusedElement is not the focused element, then set element's pop-up previously focused element to originallyFocusedElement.

The hidePopUp() method steps are:

  1. If this's popup attribute is in the no pop-up state, then throw a "NotSupportedError" DOMException.

  2. If this's pop-up visibility state is not showing, then throw an "InvalidStateError" DOMException.

  3. Run the hide pop-up algorithm given this, true, and false.

To hide a pop-up given an HTML element element, a boolean focusPreviousElement, and a boolean hideImmediately:

  1. Let document be element's node document.

  2. If element's popup attribute is in the auto state, then:

    1. Run hide all pop-ups until given element, focusPreviousElement, and hideImmediately.

    2. Run check pop-up validity given element.

      Check pop-up validity is called again because running hide all pop-ups until above could have fired the popuphide event, and an event handler could have disconnected this element or changed its popup attribute.

    3. If element's popup attribute is in the auto state, then remove the last item from document's auto pop-up list.

  3. Add element to document's pop-ups waiting to hide.

  4. Let previousAnimations be the set of all relevant Animation objects that contain at least one animation effect whose effect target is element.

  5. Set element's pop-up invoker to null.

  6. Set element's pop-up visibility state to transitioning.

  7. If hideImmediately is true, then:

    1. Queue an element task given user interaction task source and element to fire an event named popuphide at element.

    2. Run pop-up hide finish if needed given element.

    3. Return.

  8. Fire an event named popuphide at element.

  9. Run check pop-up validity given element.

    Check pop-up validity is called again because firing the popuphide event could have disconnected this element or changed its popup attribute.

  10. Let animations be the set of all relevant Animation objects that contain at least one animation effect whose effect target is element.

  11. Remove all items in animations which exist in previousAnimations.

  12. If animations is empty, then run pop-up hide finish if needed given element.

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

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

  15. If animations is not empty, then run these steps in parallel:

    1. Set element's waiting to hide pop-up to true.

    2. Wait for each animation in animations to fire either a trusted cancel event or a trusted finish event.

    3. If element's waiting to hide pop-up is true, then run pop-up hide finish if needed given element.

To finish hiding a pop-up if needed, given an HTML element element:

  1. Remove element from element's node document's pop-ups waiting to hide.

  2. Remove element from the top layer.

  3. Set element's pop-up visibility state to hidden.

  4. Set element's waiting to hide pop-up to false.

To hide all pop-ups until, given an HTML element endpoint, a boolean focusPreviousElement, and a boolean hideImmediately:

  1. Let document be endpoint's node document.

  2. If hideImmediately is true, then:

    1. For each elementWaitingToHide in document's pop-ups waiting to hide:

      1. Run pop-up hide finish if needed given elementWaitingToHide.

    2. Clear document's pop-ups waiting to hide.

  3. Let closeAllOpenPopUps be an algorithm which performs the following steps:

    1. Let popUp be document's topmost auto pop-up.

    2. While popUp is not null:

      1. Run the hide pop-up algorithm given popUp, focusPreviousElement, and hideImmediately.

      2. Set popUp to document's topmost auto pop-up.

  4. If endpoint is null, then run closeAllOpenPopUps and return.

  5. Let lastToHide be null.

  6. Let foundEndpoint be false.

  7. For each popUp in document's auto pop-up list:

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

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

  8. If foundEndpoint is false, then run closeAllOpenPopUps and return.

  9. While lastToHide is not null and lastToHide's pop-up visibility state is showing and document's auto pop-up list is not empty:

    1. Run the hide pop-up algorithm given document's auto pop-up list's last element, focusPreviousElement, and hideImmeidately.

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

To find the nearest open ancestral pop-up, given a Node node and a string ancestorType, perform the following steps. They return an HTML element or null.

  1. Let document be node's node document.

  2. Let anchorsToPopUps be an empty map.

  3. For each popUp in document's auto pop-up list:

    1. Let anchor be the result of getting the pop-up anchor element of popUp.

    2. If anchor is not null, then set anchorsToPopUps[anchor] to popUp.

  4. Let popUpPositions be an empty map.

  5. Let index be 0.

  6. For each popUp in document's auto pop-up list:

    1. Set popUpPositions[popUp] to index.

    2. Increment index by 1.

  7. If ancestorType is "new-pop-up", then:

    1. Set popUpPositions[node] to index.

  8. Let upperBound be 2147483647.

  9. If popUpPositions[node] exists, then set upperBound to popUpPositions[node].

  10. If ancestorType is "inclusive", then:

    1. Let currentNode be node.

    2. While currentNode has a parent node within the flat tree:

      1. If currentNode's popup attribute is not in the no pop-up state and currentNode's pop-up visibility state is showing and currentNode's popup attribute is not in the manual state, then:

        1. If popUpPositions[currentNode] + 1 is greater than upperBound, then set upperBound to popUpPositions[currentNode] + 1.

      2. Let targetPopUp be currentNode's pop-up target element.

      3. If targetPopUp's popup attribute is not null and targetPopUp's pop-up visibility state is showing and targetPopUp's popup attribute is not in the manual state, then:

        1. If popUpPositions[targetPopUp] + 1 is greater than upperBound, then set upperBound to popUpPositions[targetPopUp] + 1.

      4. Set currentNode to the parent node of currentNode within the flat tree.

  11. Let seen be an empty set.

  12. Return the result of finding the nearest open ancestral pop-up recursively given node, popUpPositions, anchorsToPopUps, upperBound, and seen.

To find the nearest open ancestral pop-up recursively, given a Node node, a map popUpPositions, a map anchorsToPopUps, an integer upperBound, and a set seen, perform the following steps. They return an HTML element or null.

  1. If node is null, then return null.

  2. If seen contains node, then return null.

  3. Add node to seen.

  4. Let ancestor be null.

  5. Let position be −1.

  6. Let update be an algorithm which performs the following steps given popUp:

    1. If popUp is not null and popUp's pop-up visibility state is not showing and popUp's popup attribute is not in the manual state, then:

      1. Let newPosition be popUpPositions[popUp].

      2. If newPosition is greater than position and newPosition is less than upperBound, then:

        1. Set ancestor to popUp.

        2. Set position to newPosition.

  7. Let recurseAndUpdate be an algorithm which performs the following steps given node:

    1. Let nearestOpenAncestor be the result of finding the nearest open ancestral pop-up recursively given node, popUpPositions, anchorsToPopUps, upperBound, and seen.

    2. Run update given nearestOpenAncestor.

  8. Run update given node.

  9. If popUpPositions[node] exists, then:

    1. Run recurseAndUpdate given node's pop-up anchor element.

    2. Run recurseAndUpdate given node's pop-up invoker.

  10. If node has a pop-up target element, then run recurseAndUpdate given node's pop-up target element.

  11. If anchorsToPopUps[node] exists, then run recurseAndUpdate given anchorsToPopUps[node].

  12. Run recurseAndUpdate given node's parent node in the flat tree.

  13. Return ancestor.

To get the pop-up anchor element of an HTML element element, perform the following steps. They return an HTML element or null.

  1. If element's popup attribute is in the no pop-up state, then return null.

  2. Let anchorAttribute be the result of running get an attribute by name given element and anchor.

  3. If anchorAttribute is null, then return null.

  4. Return the first HTML element in tree order, within element's root's descendants, whose ID is anchorAttribute; otherwise, if there is no such element, null.

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

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

  2. Return null.

To perform the pop-up focusing steps for an HTML element subject:

  1. Let control be the focus delegate of subject.

  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 pop-up validity for an HTML element element:

  1. If element's popup attribute is in the no pop-up state, then throw an "InvalidStateError" DOMException.

  2. If element's pop-up visibility state is not hidden, then throw an "InvalidStateError" DOMException.

  3. If element is not connected, then throw an "InvalidStateError" DOMException.

6.11.1 The pop-up target attributes

Supported elements may have the following content attributes, known as the pop-up target attributes:

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

The following shows how popupshowtarget can be used to open a pop-up:

<div popup=auto id="foo">
  This is a pop-up!
</div>

<button popupshowtarget="foo">
  Show a pop-up
</button>

The following shows how popuptoggletarget can open and close a manual pop-up, which can't be closed with light dismiss:

<div popup=manual id="foo">
  This is a pop-up!
</div>

<button popuptoggletarget="foo">
  Show or hide a pop-up
</button>

The pop-up target attributes are only supported on the following elements:

DOM interface: 
interface mixin PopUpTargetElement {
  [CEReactions] attribute DOMString? popUpToggleTarget;
  [CEReactions] attribute DOMString? popUpHideTarget;
  [CEReactions] attribute DOMString? popUpShowTarget;
};

The popUpToggleTarget IDL attribute must reflect the popuptoggletarget attribute.

The popUpHideTarget IDL attribute must reflect the popuphidetarget attribute.

The popUpShowTarget IDL attribute must reflect the popupshowtarget attribute.

To run the pop-up target attribute activation behavior given a Node node:

  1. If node is disabled, then return.

  2. If node is not supported by the pop-up target attributes, then return.

  3. Let popUp be node's pop-up target element.

  4. If popUp is null, then return.

  5. If node doesn't have the popuptoggletarget attribute, then:

    1. If node has the popupshowtarget attribute and popUp's pop-up visibility state is showing, then return.

    2. If node has the popuphidetarget attribute and popUp's pop-up visibility state is hidden, then return.

    3. If node doesn't have the popupshowtarget attribute and node doesn't have the popuphidetarget attribute, then return.

  6. If node has a form owner and node is in any of the following states, then return:

  7. If popUp's pop-up visibility state is showing, then run the hide pop-up algorithm given popUp, true, and false.

  8. Otherwise:

    1. Set popUp's pop-up invoker to node.

    2. Run show pop-up given popUp.

To get the pop-up 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. Let idref be null.

  3. If node has the popuptoggletarget attribute, then set idref to the value of node's popuptoggletarget attribute.

  4. Otherwise, if node has the popupshowtarget attribute, then set idref to the value of node's popupshowtarget attribute.

  5. Otherwise, if node has the popuphidetarget attribute, then set idref to the value of node's popuphidetarget attribute.

  6. If idref is null, then return null.

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

  8. If popupElement is null, then return null.

  9. If popupElement's popup attribute is in the no pop-up state, then return null.

  10. Return popupElement.

6.11.2 Pop-up light dismiss

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

To light dismiss open pop-ups, given an Event event and a Node node:

  1. If node is not a Document, then return.

  2. Let topmostPopup be the result of running topmost auto pop-up given node.

  3. If topmostPopup is null, then return.

  4. Let target be event's target.

  5. If event is a pointerdown event, then:

    1. Set node's pop-up pointerdown target to the result of running nearest open ancestral pop-up given target and "inclusive".

  6. If event is a pointerup event, then:

    1. Let ancestor be the result of running nearest open ancestral pop-up given target and "inclusive".

    2. Let sameTarget be true if ancestor is node's pop-up pointerdown target.

    3. Set node's pop-up pointerdown target to null.

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

  7. If event is a keydown event for the Escape key, then:

    1. Run the hide pop-up algorithm given topmostPopup, true, and false.

6.11.3 The defaultopen attribute

All HTML elements may have the defaultopen content attribute set. When specified on an element whose popup attribute is not in the no pop-up state, it makes the element shown automatically when the page is loaded. defaultopen is a boolean attribute.

The defaultOpen IDL attribute must reflect the defaultopen content attribute.

6.11.4 The anchor attribute

All HTML elements may have the anchor attribute set. When specified on an element whose popup attribute is not in the no pop-up state, the value of the attribute is used as an ID to refer to another element. The other element is considered to be a parent in the pop-up hierarchy. This means, for example, that if the element and parent element's popup attributes are in the auto state, then both of them can be open at the same time even though only one auto pop-up is supposed to be open at a time.