davidbgk
/
larlet-fr-david-cache


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462
							<!doctype html><!-- This is a valid HTML5 document. -->
<!-- Screen readers, SEO, extensions and so on. -->
<html lang="en">
<!-- Has to be within the first 1024 bytes, hence before the `title` element
  See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset -->
<meta charset="utf-8">
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 -->
<!-- The viewport meta is quite crowded and we are responsible for that.
  See: https://codepen.io/tigt/post/meta-viewport-for-2015 -->
<meta name="viewport" content="width=device-width,initial-scale=1">
<!-- Required to make a valid HTML5 document. -->
<title>Popover API (Explainer) (archive) — David Larlet</title>
<meta name="description" content="Publication mise en cache pour en conserver une trace.">
<!-- That good ol' feed, subscribe :). -->
<link rel="alternate" type="application/atom+xml" title="Feed" href="/david/log/">
<!-- Generated from https://realfavicongenerator.net/ such a mess. -->
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons2/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons2/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons2/favicon-16x16.png">
<link rel="manifest" href="/static/david/icons2/site.webmanifest">
<link rel="mask-icon" href="/static/david/icons2/safari-pinned-tab.svg" color="#07486c">
<link rel="shortcut icon" href="/static/david/icons2/favicon.ico">
<meta name="msapplication-TileColor" content="#f7f7f7">
<meta name="msapplication-config" content="/static/david/icons2/browserconfig.xml">
<meta name="theme-color" content="#f7f7f7" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#272727" media="(prefers-color-scheme: dark)">
<!-- Is that even respected? Retrospectively? What a shAItshow…
  https://neil-clarke.com/block-the-bots-that-feed-ai-models-by-scraping-your-website/ -->
<meta name="robots" content="noai, noimageai">
<!-- Documented, feel free to shoot an email. -->
<link rel="stylesheet" href="/static/david/css/style_2021-01-20.css">
<!-- See https://www.zachleat.com/web/comprehensive-webfonts/ for the trade-off. -->
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<script>
    function toggleTheme(themeName) {
        document.documentElement.classList.toggle(
            'forced-dark',
            themeName === 'dark'
        )
        document.documentElement.classList.toggle(
            'forced-light',
            themeName === 'light'
        )
    }
    const selectedTheme = localStorage.getItem('theme')
    if (selectedTheme !== 'undefined') {
        toggleTheme(selectedTheme)
    }
</script>

  <meta name="robots" content="noindex, nofollow">
  <meta content="origin-when-cross-origin" name="referrer">
  <!-- Canonical URL for SEO purposes -->
  <link rel="canonical" href="https://open-ui.org/components/popover.research.explainer/">

<body class="remarkdown h1-underline h2-underline h3-underline em-underscore hr-center ul-star pre-tick" data-instant-intensity="viewport-all">


<article>
  <header>
    <h1>Popover API (Explainer)</h1>
  </header>
  <nav>
    <p class="center">
      <a href="/david/" title="Aller à l’accueil"><svg class="icon icon-home">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-home"></use>
      </svg> Accueil</a> •
      <a href="https://open-ui.org/components/popover.research.explainer/" title="Lien vers le contenu original">Source originale</a>
      <br>
      Mis en cache le 2024-02-03
    </p>
  </nav>
  <hr>
  <ul><li><a href="https://github.com/mfreed7">@mfreed7</a>, <a href="https://github.com/scottaohara">@scottaohara</a>, <a href="https://github.com/BoCupp-Microsoft">@BoCupp-Microsoft</a>, <a href="https://github.com/domenic">@domenic</a>, <a href="https://github.com/gregwhitworth">@gregwhitworth</a>, <a href="https://github.com/chrishtr">@chrishtr</a>, <a href="https://github.com/dandclark">@dandclark</a>, <a href="https://github.com/una">@una</a>, <a href="https://github.com/smhigley">@smhigley</a>, <a href="https://github.com/aleventhal">@aleventhal</a>, <a href="https://github.com/jh3y">@jh3y</a></li><li>May 4, 2023</li></ul>
<p><strong>NOTE:</strong> This Popover API explainer was mostly useful during the development of the feature. While it is roughly still in line with the actual feature, it might be more informative to look at either of these two sources of documentation:</p>
<ol><li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Popover_API">The MDN page documenting the Popover API</a></li><li><a href="https://html.spec.whatwg.org/multipage/C#the-popover-attribute">The HTML spec for the popover attribute</a></li></ol>
<p>A very common UI pattern on the Web, for which there is no native API, is “popover UI”, also sometimes called “popovers”, “pop up UI”, or “popovers”. Popovers are a general class of UI that have three common behaviors:</p>
<ol><li>Popovers always appear <strong>on top of other page content</strong>.</li><li>Popovers are <strong>ephemeral</strong>. When the user “moves on” to another part of the page (e.g. by clicking elsewhere, or hitting ESC), the popover hides.</li><li>Popovers (of a particular type) are generally <strong>“one at a time”</strong> - opening one popover closes others.</li></ol>
<p>This document proposes a set of APIs to make this type of UI easy to build.</p>
<p>Here are the goals for this API:</p>
<ul><li>Allow any element and its (arbitrary) descendants to be rendered on top of <strong>all other content</strong> in the host web application.</li><li>Include <strong>“light dismiss” management functionality</strong>, to remove the element/descendants from the top-layer upon certain actions such as hitting Esc (or any <a href="https://wicg.github.io/close-watcher/#close-signal">close signal</a>) or clicking outside the element bounds.</li><li>Allow this “top layer” content to be fully styled, sized, and positioned at the author’s discretion, including properties which require compositing with other layers of the host web application (e.g. the box-shadow or backdrop-filter CSS properties).</li><li>Allow these top layer elements to reside at semantically-relevant positions in the DOM. I.e. it should not be required to re-parent a top layer element as the last child of the <code>document.body</code> simply to escape ancestor containment and transforms.</li><li>Include an appropriate user input and focus management experience, with flexibility to modify behaviors such as initial focus.</li><li><strong>Accessible by default</strong>, with the ability to further extend semantics/behaviors as needed for the author’s specific use case.</li><li>Avoid developer footguns, such as improper stacking of dialogs and popovers, and incorrect accessibility mappings.</li><li>Avoid the need for any JavaScript for most common cases.</li><li>Easy animation of show/hide operations.</li></ul>
<p>See the <a href="https://open-ui.org/components/popup.research.explainer-v1">original <code>&lt;popup&gt;</code> element explainer</a>, and also the comments on <a href="https://github.com/openui/open-ui/issues/410">Issue 410</a> and <a href="https://github.com/openui/open-ui/issues/417">Issue 417</a>. See also <a href="https://github.com/w3c/csswg-drafts/issues/6965">this CSSWG discussion</a> which has mostly been about a CSS alternative for top layer.</p>
<p>This proposal was discussed in OpenUI on <a href="https://github.com/openui/open-ui/issues/455">Issue 455</a>, which was closed as <a href="https://github.com/openui/open-ui/issues/455#issuecomment-1050172067">resolved</a>. In WHATWG/html, <a href="https://github.com/whatwg/html/issues/7785">Issue 7785</a> tracks the addition of this feature.</p>
<p>There have been <strong>many</strong> discussions and resolutions at OpenUI of various aspects of this proposal, and those are listed in the <a href="#design-decisions-via-openui">Design Decisions</a> section. Requests for standards positions have been requested from <a href="https://github.com/mozilla/standards-positions/issues/698">Gecko</a> and <a href="https://github.com/WebKit/standards-positions/issues/74">WebKit</a>.</p>
<p>There have been three TAG reviews for this set of functionality: <a href="https://github.com/w3ctag/design-reviews/issues/599">#599</a> (closed waiting for anchor positioning), <a href="https://github.com/w3ctag/design-reviews/issues/680">#680</a> (closed recommending change from <code>&lt;popup&gt;</code> to <code>popup</code> attribute), <a href="https://github.com/w3ctag/design-reviews/issues/743">#743</a> (open).</p>
<p>A natural question that <a href="https://github.com/openui/open-ui/issues/581">commonly arises</a> is: what’s the difference between a “popover” and a “dialog”? There are two ways to interpret this question:</p>
<ol><li>What are the difference between these general UX patterns and words?</li><li>What are the technical implementation differences between <code>&lt;div popover&gt;</code> and <code>&lt;dialog&gt;</code>?</li></ol>
<p>In both cases, an important distinction needs to be made between <strong>modal</strong> and <strong>non-modal</strong> (or <strong>modeless</strong>) dialogs. With a <strong>modal</strong> dialog, the rest of the page (outside the dialog) is rendered <strong><code>inert</code></strong>, so that only the contents of the dialog are interactable. Importantly, a popover is <strong>non-modal</strong>. Almost by definition, a popover is not permanent: it goes away (via light dismiss) when the user changes their attention to something else, by clicking or tabbing to something else. For these reasons, if the dialog in question needs to be <strong>modal</strong>, then the <code>&lt;dialog&gt;</code> element is the way to go.</p>
<p>Having said that, dialogs can also be <strong>non-modal</strong>, and popovers can be set to not light-dismiss (via <strong><code>popover=manual</code></strong>). There is a significant area of overlap between the two Web features. Some use cases that lie in this area of overlap include:</p>
<ol><li>“Toasts” or asynchronous notifications, which stay onscreen until dismissed manually or via a timer.</li><li>Persistent UI, such as teaching-UI, that needs to stay on screen while the user interacts with the page.</li><li>Custom components that need to “manually” control popover behavior.</li></ol>
<p>Given these use cases, it’s important to call out the technical differences between a non-modal <code>&lt;dialog&gt;</code> and a <code>&lt;div popover=manual&gt;</code>:</p>
<ul><li>A <code>&lt;div popover=manual&gt;</code> is <strong>in the top layer</strong>, so it draws on top of other content. The same is not true for a non-modal <code>&lt;dialog&gt;</code>. This is likely the most impactful difference, as it tends to be difficult to ensure that a non-modal <code>&lt;dialog&gt;</code> is painted on top of other page content.</li><li>A <code>&lt;dialog&gt;</code> element always has <strong><code>role=dialog</code></strong>, while the <code>popover</code> attribute can be applied to the <strong>most-semantically-relevant HTML element</strong>, including the <code>&lt;dialog&gt;</code> element itself: <code>&lt;dialog popover&gt;</code>.</li><li>The popover API comes with some <strong>“nice to haves”</strong>:<ul><li>popovers are easy to animate both the show and hide transitions, via pure CSS. In contrast, JS is required in order to animate <code>dialog.close()</code>.</li><li>popovers work with the invoking attributes (e.g. <code>popovertarget</code>) to declaratively show/hide them with pure HTML. In contrast, JS is required to show/close a <code>&lt;dialog&gt;</code>.</li><li>popovers fire both a “popovershow” and a “popoverhide” event. In contrast, a <code>&lt;dialog&gt;</code> only fires <code>cancel</code> and <code>close</code>, but no event is fired when it is shown.</li></ul></li></ul>
<p>For the above reasons, it seems clear that for use cases that need a <strong>non-modal</strong> dialog which has popover behavior, a <code>&lt;dialog popover&gt;</code> (with the most appropriate value for the <code>popover</code> attribute) should be preferred. Importantly, if the use case is <strong>not</strong> meant to be exposed as a “dialog”, then another (non-<code>&lt;dialog&gt;</code>) element should be used with the <code>popover</code> attribute, or a generic <code>&lt;div popover role=something&gt;</code> should be used with the appropriate role added.</p>
<p>This section lays out the full details of this proposal. If you’d prefer, you can <strong><a href="#example-use-cases">skip to the examples section</a> to see the code</strong>.</p>
<p>A new content attribute, <strong><code>popover</code></strong>, controls both the top layer status and the dismiss behavior. There are several allowed values for this attribute:</p>
<ul><li><strong><code>popover=auto</code></strong> - A top layer element following “Auto” dismiss behaviors (see below).</li><li><strong><code>popover=manual</code></strong> - A top layer element following “Manual” dismiss behaviors (see below).</li></ul>
<p>Additional values for the <code>popover</code> attribute may become available in the future.</p>
<p>So this markup represents popover content:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>div</span><span> popover</span><span>=</span><span>"auto"</span><span>&gt;I am a popover&lt;/</span><span>div</span><span>&gt;</span></span></code></pre>
<p>As written above, the <code>&lt;div&gt;</code> will be rendered <code>display:none</code> by the UA stylesheet, meaning it will not be shown when the page is loaded. To show the popover, one of several methods can be used: <a href="#declarative-triggers">declarative triggering</a>, <a href="#javascript-trigger">JavaScript triggering</a>.</p>
<p>Additionally, the <code>popover</code> attribute can be used without a value (or with an empty string <code>""</code> value), and in that case it will behave identically to <code>popover=auto</code>:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>div</span><span> popover</span><span>=</span><span>"auto"</span><span>&gt;I am a popover&lt;/</span><span>div</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>div</span><span> popover</span><span>&gt;I am also an "auto" popover&lt;/</span><span>div</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>div</span><span> popover</span><span>=</span><span>""</span><span>&gt;So am I&lt;/</span><span>div</span><span>&gt;</span></span></code></pre>
<p>For convenience and brevity, the remainder of this explainer will use this boolean-like syntax in most cases, e.g. <code>&lt;div popover&gt;</code>.</p>
<p>There are several ways to “show” a popover, and they are discussed in this section. When any of these methods are used to show a popover, it will be made visible and moved (by the UA) to the <a href="https://fullscreen.spec.whatwg.org/#top-layer">top layer</a>. The top layer is a layer that paints on top of all other page content, with the exception of other elements currently in the top layer. This allows, for example, a “stack” of popovers to exist.</p>
<blockquote><p>Note: It is intended that <a href="/components/invokers.explainer"><code>invoketarget</code></a> will replace <code>popovertarget</code> leading to <code>popovertarget</code>’s eventual deprecation.</p></blockquote>
<p>A common design pattern is to have a button which makes a popover visible. To facilitate this pattern, and avoid the need for JavaScript in this common case, two content attributes (<code>popovertarget</code> and <code>popovertargetaction</code>) allow the developer to declaratively toggle, show, or hide a popover. To do so, the attribute’s value should be set to the idref of another element:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>button</span><span> popovertarget</span><span>=</span><span>"foo"</span><span>&gt;Toggle the popover&lt;/</span><span>button</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>div</span><span> id</span><span>=</span><span>"foo"</span><span> popover</span><span>&gt;Popover content&lt;/</span><span>div</span><span>&gt;</span></span></code></pre>
<p>When the button in this example is activated, the UA will call <code>.showPopover()</code> on the <code>&lt;div id=foo popover&gt;</code> element if it is currently hidden, or <code>hidePopover()</code> if it is showing. In this way, no JavaScript will be necessary for this use case.</p>
<p>If the desire is to have a button that only shows or only hides a popover, the following markup can be used:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>button</span><span> popovertarget</span><span>=</span><span>"foo"</span><span>&gt;Toggle the popover&lt;/</span><span>button</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>button</span><span> popovertarget</span><span>=</span><span>"foo"</span><span> popovertargetaction</span><span>=</span><span>"show"</span><span>&gt;This button only shows the popover&lt;/</span><span>button</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>button</span><span> popovertarget</span><span>=</span><span>"foo"</span><span> popovertargetaction</span><span>=</span><span>"hide"</span><span>&gt;This button only hides the popover&lt;/</span><span>button</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>div</span><span> id</span><span>=</span><span>"foo"</span><span> popover</span><span>&gt;Popover content&lt;/</span><span>div</span><span>&gt;</span></span></code></pre>
<p>Note that the default value for <code>popovertargetaction</code> is “toggle” which can also be explicitly specified.</p>
<p>When the <code>popovertarget</code> attribute is applied to an activating element, the UA will automatically map this element with the appropriate accessibility semantics. For instance, the initial implementation will expose the appropriate <code>aria-expanded</code> state based on whether the popover is shown or hidden. As the popover API matures, there may need to be further discussion with the ARIA working group to determine if additional ARIA semantics, if any, are necessary.</p>
<p>These attributes are only supported on buttons (including <code>&lt;button&gt;</code>, <code>&lt;input type=button&gt;</code>, etc.) as long as the button would not otherwise submit a form. For example, this is not supported: <code>&lt;form&gt;&lt;input type=submit popovertarget=foo&gt;&lt;/form&gt;</code>. In that case, the form would be submitted, and the popover would <strong>not</strong> be toggled.</p>
<p>The declarative trigger attributes can also be accessed via IDL:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>// Note that `popoverTargetElement` directly sets an element reference:</span></span>
<span class="line"><span>myButton.popoverTargetElement </span><span>=</span><span> myElement</span></span>
<span class="line"><span>myButton.popoverTargetAction </span><span>=</span><span> 'show'</span></span></code></pre>
<p>To show and hide the popover via JavaScript, there are three methods on HTMLElement:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>const</span><span> popover</span><span> =</span><span> document.</span><span>querySelector</span><span>(</span><span>'[popover]'</span><span>)</span></span>
<span class="line"><span>popover.</span><span>showPopover</span><span>() </span><span>// Show the popover</span></span>
<span class="line"><span>popover.</span><span>hidePopover</span><span>() </span><span>// Hide a visible popover</span></span>
<span class="line"><span>popover.</span><span>togglePopover</span><span>() </span><span>// Toggle the open/closed state of a popover</span></span></code></pre>
<p>Calling <code>showPopover()</code> on an element that has a valid value for the <code>popover</code> attribute will cause the UA to remove the <code>display:none</code> rule from the element and move it to the top layer. Calling <code>hidePopover()</code> on a showing popover will remove it from the top layer, and re-apply <code>display:none</code>.</p>
<p>There are several conditions that will cause <code>showPopover()</code>, <code>hidePopover()</code>, and <code>togglePopover()</code> to throw an exception:</p>
<ol><li>Calling <code>showPopover()</code> on a valid popover that is already in the showing state. This will throw an <code>InvalidStateError</code> <code>DOMException</code>.</li><li>Calling <code>hidePopover()</code> on a valid popover that is not currently showing. This will throw an <code>InvalidStateError</code> <code>DOMException</code>.</li><li>Calling any of the three methods on an element that does not contain a <a href="#html-content-attribute">valid value</a> of the <code>popover</code> attribute. This will throw a <code>NotSupportedError</code> <code>DOMException</code>.</li><li>Calling any of the three methods on a valid popover that is not connected to a document. This will throw an <code>InvalidStateError</code> <code>DOMException</code>.</li></ol>
<p>When a popover is open, it will match the <code>:popover-open</code> pseudo class:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>const</span><span> popover</span><span> =</span><span> document.</span><span>createElement</span><span>(</span><span>'div'</span><span>)</span></span>
<span class="line"><span>popover.popover </span><span>=</span><span> 'auto'</span></span>
<span class="line"><span>popover.</span><span>matches</span><span>(</span><span>':popover-open'</span><span>) </span><span>===</span><span> false</span></span>
<span class="line"><span>popover.</span><span>showPopover</span><span>()</span></span>
<span class="line"><span>popover.</span><span>matches</span><span>(</span><span>':popover-open'</span><span>) </span><span>===</span><span> true</span></span></code></pre>
<p>The UA stylesheet for popovers will look like this:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>[</span><span>popover</span><span>] {</span></span>
<span class="line"><span>  position</span><span>: </span><span>fixed</span><span>;</span></span>
<span class="line"><span>  inset</span><span>: </span><span>0</span><span>;</span></span>
<span class="line"><span>  width</span><span>: </span><span>fit-content</span><span>;</span></span>
<span class="line"><span>  height</span><span>: </span><span>fit-content</span><span>;</span></span>
<span class="line"><span>  margin</span><span>: </span><span>auto</span><span>;</span></span>
<span class="line"><span>  border</span><span>: </span><span>solid</span><span>;</span></span>
<span class="line"><span>  padding</span><span>: </span><span>0.25</span><span>em</span><span>;</span></span>
<span class="line"><span>  overflow</span><span>: </span><span>auto</span><span>;</span></span>
<span class="line"><span>  color</span><span>: CanvasText;</span></span>
<span class="line"><span>  background-color</span><span>: Canvas;</span></span>
<span class="line"><span>}</span></span>
<span class="line"></span>
<span class="line"><span>[</span><span>popover</span><span>]</span><span>::backdrop</span><span> {</span></span>
<span class="line"><span>    pointer-events</span><span>: </span><span>none</span><span> !important</span><span>;</span></span>
<span class="line"><span>}</span></span>
<span class="line"></span>
<span class="line"><span>[</span><span>popover</span><span>]{</span><span>match</span><span> this</span><span> when</span><span> popover</span><span> is</span><span> hidden</span><span>} {</span></span>
<span class="line"><span>  display</span><span>: </span><span>none</span><span>;</span></span>
<span class="line"><span>}</span></span></code></pre>
<p>As seen above, the styling rules manage “showing” vs. “hidden” via these UA stylesheet rules:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>[</span><span>popover</span><span>]{</span><span>when</span><span> hidden</span><span>}: {</span></span>
<span class="line"><span>  display</span><span>: </span><span>none</span><span>;</span></span>
<span class="line"><span>}</span></span>
<span class="line"><span>[</span><span>popover</span><span>] {</span></span>
<span class="line"><span>  position</span><span>: </span><span>fixed</span><span>;</span></span>
<span class="line"><span>}</span></span></code></pre>
<p>The above rules mean that a popover, when not “shown”, has <code>display:none</code> applied, and that style is removed when one of the methods above is used to show the popover. Note that the <code>display:none</code> UA stylesheet rule is not <code>!important</code>. In other words, developer style rules can be used to override this UA style to make a not-showing popover visible in the page. In this case, the popover will <strong>not</strong> be displayed in the top layer, but rather at its ordinary <code>z-index</code> position within the document. This can be used, for example, to make popover content “return to the page” instead of becoming hidden. Care must be taken, if the <code>display</code> property is set by developer CSS, to ensure the popover visibility isn’t adversely affected. For example, developer CSS could do this:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>[</span><span>popover</span><span>] {</span></span>
<span class="line"><span>  /* Make the popover a flexbox: */</span></span>
<span class="line"><span>  display</span><span>: </span><span>flex</span><span>;</span></span>
<span class="line"><span>}</span></span>
<span class="line"><span>[</span><span>popover</span><span>]</span><span>:not</span><span>(:</span><span>popover-open</span><span>) {</span></span>
<span class="line"><span>  /* But make sure not to show it unless it's open: */</span></span>
<span class="line"><span>  display</span><span>: </span><span>none</span><span>;</span></span>
<span class="line"><span>}</span></span></code></pre>
<p>Be mindful when using other stylesheets that you haven’t authored. These may set the <code>display</code> value on your popover elements. For example, if you use a <code>menu</code> element as a <code>popover</code> and you use earlier versions of <a href="https://necolas.github.io/normalize.css/">normalize.css</a>. In this case, normalize.css has a rule that sets <code>display: flex</code> on <code>menu</code> elements.</p>
<p>An early version of the Popover API included custom behaviors to make animations and transitions of popovers trivially easy. During the standardization process, however, this functionality was removed, with the intention to replace it with a more general capability for the web platform that also applies to other top layer elements. This section describes how that new set of capabilities will work together to help animate popovers (and modal <code>&lt;dialog&gt;</code>s). There is also <a href="https://github.com/chrishtr/rendering/blob/master/entry-exit-animations.md">a separate explainer</a> for this set of features.</p>
<p>The new capabilities include the ones described in these five CSSWG issues:</p>
<p>Assuming all five of the above features land in specs and browsers in roughly the form they’re currently being discussed, then to animate a popover’s show/hide transitions you would use:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>[</span><span>popover</span><span>] {</span></span>
<span class="line"><span>  --transition-time</span><span>: </span><span>0.5</span><span>s</span><span>;</span></span>
<span class="line"><span>  transition</span><span>: display </span><span>var</span><span>(</span><span>--transition-time</span><span>), overlay-behavior </span><span>var</span><span>(</span><span>--transition-time</span><span>),</span></span>
<span class="line"><span>    opacity </span><span>var</span><span>(</span><span>--transition-time</span><span>);</span></span>
<span class="line"><span>}</span></span>
<span class="line"><span>[</span><span>popover</span><span>]:</span><span>popover-open</span><span> {</span></span>
<span class="line"><span>  @</span><span>initial</span><span> {</span></span>
<span class="line"><span>    opacity</span><span>: </span><span>0</span><span>;</span></span>
<span class="line"><span>  }</span></span>
<span class="line"><span>  opacity: 1;</span></span>
<span class="line"><span>}</span></span></code></pre>
<p>The above CSS will result in the opacity (and also <code>display</code> and top-layer-ness) being transitioned during both show and hide transitions.</p>
<p>This can also be achieved with the equivalent CSS animations:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>[</span><span>popover</span><span>]:</span><span>popover-open</span><span> {</span></span>
<span class="line"><span>  animation</span><span>: fadein </span><span>0.5</span><span>s</span><span>;</span></span>
<span class="line"><span>  transition</span><span>: overlay-behavior </span><span>0.5</span><span>s</span><span>;</span></span>
<span class="line"><span>  opacity</span><span>: </span><span>1</span><span>; </span><span>/* UA default */</span></span>
<span class="line"><span>}</span></span>
<span class="line"><span>@keyframes</span><span> fadein</span><span> {</span></span>
<span class="line"><span>  from</span><span> {</span></span>
<span class="line"><span>    opacity</span><span>: </span><span>0</span><span>;</span></span>
<span class="line"><span>  }</span></span>
<span class="line"><span>}</span></span>
<span class="line"><span>[</span><span>popover</span><span>]:closed {</span></span>
<span class="line"><span>  animation</span><span>: fadeout </span><span>0.5</span><span>s</span><span>;</span></span>
<span class="line"><span>}</span></span>
<span class="line"><span>@keyframes</span><span> fadeout</span><span> {</span></span>
<span class="line"><span>  from</span><span> {</span></span>
<span class="line"><span>    display</span><span>: </span><span>block</span><span>;</span></span>
<span class="line"><span>  }</span></span>
<span class="line"><span>  to</span><span> {</span></span>
<span class="line"><span>    opacity</span><span>: </span><span>0</span><span>;</span></span>
<span class="line"><span>  }</span></span>
<span class="line"><span>}</span></span></code></pre>
<p>Again, the above descriptions depend on all five CSSWG issues above landing in standards and browsers.</p>
<p>The <code>popover</code> content attribute will be <a href="https://html.spec.whatwg.org/#reflect">reflected</a> as a nullable IDL attribute:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>[Exposed=Window]</span></span>
<span class="line"><span>partial interface Element {</span></span>
<span class="line"><span>  attribute DOMString? popover;</span></span>
<span class="line"><span>}</span></span></code></pre>
<p>This not only allows developer ease-of-use from JavaScript, but also allows for a feature detection mechanism:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>function</span><span> supportsPopover</span><span>() {</span></span>
<span class="line"><span>  return</span><span> HTMLElement</span><span>.</span><span>prototype</span><span>.</span><span>hasOwnProperty</span><span>(</span><span>'popover'</span><span>)</span></span>
<span class="line"><span>}</span></span></code></pre>
<p>Further, only <a href="#html-content-attribute">valid values</a> of the content attribute will be reflected to the IDL property, with invalid values being reflected as the value <code>manual</code>. For example:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>const</span><span> div</span><span> =</span><span> document.</span><span>createElement</span><span>(</span><span>'div'</span><span>)</span></span>
<span class="line"><span>div.</span><span>setAttribute</span><span>(</span><span>'popover'</span><span>, </span><span>'AUTO'</span><span>)</span></span>
<span class="line"><span>div.popover </span><span>===</span><span> 'auto'</span><span> // true (note lowercase)</span></span>
<span class="line"><span>div.</span><span>setAttribute</span><span>(</span><span>'popover'</span><span>, </span><span>'invalid!'</span><span>)</span></span>
<span class="line"><span>div.popover </span><span>===</span><span> 'manual'</span><span> // true</span></span>
<span class="line"><span>div.</span><span>removeAttribute</span><span>(</span><span>'popover'</span><span>)</span></span>
<span class="line"><span>div.popover </span><span>===</span><span> null</span><span> // true</span></span></code></pre>
<p>This allows feature detection of the values, for forward compatibility:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>function</span><span> supportsPopoverType</span><span>(</span><span>type</span><span>) {</span></span>
<span class="line"><span>  if</span><span> (</span><span>!</span><span>HTMLElement</span><span>.</span><span>prototype</span><span>.</span><span>hasOwnProperty</span><span>(</span><span>'popover'</span><span>)) </span><span>return</span><span> false</span><span> // Popover API not supported</span></span>
<span class="line"><span>  const</span><span> testElement</span><span> =</span><span> document.</span><span>createElement</span><span>(</span><span>'div'</span><span>)</span></span>
<span class="line"><span>  testElement.popover </span><span>=</span><span> type</span></span>
<span class="line"><span>  return</span><span> testElement.popover </span><span>==</span><span> type.</span><span>toLowerCase</span><span>()</span></span>
<span class="line"><span>}</span></span>
<span class="line"><span>supportsPopoverType</span><span>(</span><span>'manual'</span><span>) </span><span>===</span><span> true</span></span>
<span class="line"><span>supportsPopoverType</span><span>(</span><span>'invalid!'</span><span>) </span><span>===</span><span> false</span></span></code></pre>
<p>An event is fired synchronously when a popover is shown or hidden. This event can be used, for example, to populate content for the popover just in time before it is shown, or update server data when it closes. The event provides a <code>currentState</code> and <code>newState</code> for the popover. The value of these properties can either be “open” or “closed”. The events looks like this:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>const</span><span> popover</span><span> =</span><span> Object.</span><span>assign</span><span>(document.</span><span>createElement</span><span>(</span><span>'div'</span><span>), { popover: </span><span>'auto'</span><span> })</span></span>
<span class="line"><span>popover.</span><span>addEventListener</span><span>(</span><span>'beforetoggle'</span><span>, ({ </span><span>currentState</span><span>, </span><span>newState</span><span> }) </span><span>=&gt;</span><span> {</span></span>
<span class="line"><span>  if</span><span> (currentState </span><span>===</span><span> 'closed'</span><span>) console.</span><span>info</span><span>(</span><span>'Popover is closed'</span><span>)</span></span>
<span class="line"><span>  if</span><span> (newState </span><span>===</span><span> 'open'</span><span>) console.</span><span>info</span><span>(</span><span>'Popover is being shown'</span><span>)</span></span>
<span class="line"><span>})</span></span></code></pre>
<p>The <code>beforetoggle</code> event is cancellable when the <code>newState</code> is equal to “open”. Doing so keeps the popover from being shown. You can’t cancel the hiding of a popover as that would interfere with the one-at-a-time and light-dismiss behaviors. The <code>beforetoggle</code> event is fired synchronously.</p>
<p>Elements that move into the top layer may require focus to be moved to that element, or a descendant element. However, not all elements in the top layer will require focus. For example, a modal <code>&lt;dialog&gt;</code> will have focus set to its first interactive element, if not the dialog element itself, because a modal dialog is something that requires immediate attention. On the other hand, a <code>&lt;div popover=manual&gt;</code>, which may represent a dynamic notification message (commonly referred to as a “notification”, “toast”, or “alert”), or potentially a persistent chat widget, should not immediately receive focus, even if it contains focusable elements. This is because such popovers are meant for out-of-band communication of state, and are not meant to interrupt a user’s current action. Additionally, if the top layer element <strong>should</strong> receive immediate focus, there is a question about <strong>which</strong> part of the element gets that initial focus. For example, the element itself could receive focus, or one of its focusable descendants could receive focus.</p>
<p>To provide control over these behaviors, the <code>autofocus</code> attribute can be used on or within popovers. When present on a popover or one of its descendants, it will result in focus being moved to the popover or the specified element when the popover is shown. Note that <code>autofocus</code> is <a href="https://html.spec.whatwg.org/multipage/interaction.html#the-autofocus-attribute">already a global attribute</a>, but the existing behavior applies to element focus on <strong>page load</strong>. This proposal extends that definition to be used within popovers, and the focus behavior happens <strong>when they are shown</strong>. Note that adding <code>autofocus</code> to a popover descendant does <strong>not</strong> cause the popover to be shown on page load, and therefore it does not cause focus to be moved into the popover <strong>on page load</strong>, unless the <code>defaultopen</code> attribute is also used.</p>
<p>The <code>autofocus</code> attribute allows control over the focus behavior when the popover is shown. When the popover is hidden, often the most user friendly thing to do is to return focus to the previously-focused element. The <code>&lt;dialog&gt;</code> element currently behaves this way. However, for popovers, there are some nuances. For example, if the popover is being hidden via light dismiss, because the user clicked on another element outside the popover, the focus should <strong>not</strong> be returned to another element, it should go to the clicked element (if focusable, or <code>&lt;body&gt;</code> if not). There are a number of other such considerations. The behavior on hiding the popover is:</p>
<ul><li><p>A popover element has a <strong>previously focused element</strong>, initially <code>null</code>, which is set equal to <code>document.activeElement</code> when the popover is shown, if a) the popover is a <code>auto</code> popover, and b) if the <a href="#the-popover-stack">popover stack</a> is currently empty. The <strong>previously focused element</strong> is set back to <code>null</code> when a popover is hidden.</p></li><li><p>When a popover is hidden, focus is set back to the <strong>previously focused element</strong>, if it is non-<code>null</code>, in the following cases:</p><ol><li>Light dismiss via <a href="https://wicg.github.io/close-watcher/#close-signal">close signal</a> (e.g. Escape key pressed).</li><li>Hide popover from JavaScript via <code>hidePopover()</code>.</li><li>Hide popover via a <strong>popover-contained</strong>* triggering element with `popovertargetaction=“hide” or “toggle”. The triggering element must be popover-contained, otherwise the keyboard or mouse activation of the triggering element should have already moved focus to that element.</li><li>Hide popover because its <code>popover</code> type changes (e.g. via <code>myPopover.popover='something else';</code>).</li></ol></li><li><p>Any other actions which hide the popover will <strong>not</strong> cause the focus to be changed when the popover hides. In these cases, the “normal” behavior happens for each action. Some examples include:</p><ol><li>Click outside the popover (focus the clicked thing).</li><li>Click on a <strong>non-popover-contained</strong>* triggering element to close popover (focus the triggering element). This is a special case of the point just above.</li><li>Tab-navigate (focus the next tabbable element in the document’s focus order).</li><li>Hide popover because it was removed from the document (event handlers not allowed while removing elements).</li><li>Hide popover when a modal dialog or fullscreen element is shown (follow dialog/fullscreen focusing steps).</li><li>Hide popover via <code>showPopover()</code> on another popover that hides this one (follow new popover focusing steps).</li></ol></li></ul>
<p>The intention of the above set of behaviors is to return focus to the previously focused element when that makes sense, and not do so when the user’s intention is to move focus elsewhere or when it would be confusing.</p>
<p>* In the above, “a popover contained triggering element” means the triggering element is contained within <strong>the popover being hidden</strong>, not any arbitrary popover.</p>
<p>A new attribute, <code>anchor</code>, can be used on a popover element to refer to the popover’s “anchor”. The value of the attribute is a string idref corresponding to the <code>id</code> of another element (the “anchor element”). This anchoring relationship is used for two things:</p>
<ol><li>Establish the provided anchor element as an <a href="#nearest-open-ancestral-popover">“ancestor”</a> of this popover, for light-dismiss behaviors. In other words, the <code>anchor</code> attribute can be used to form nested popovers.</li><li>The referenced anchor element could be used by the <a href="https://drafts.csswg.org/css-anchor-1/">Anchor Positioning feature</a>.</li></ol>
<p>The anchor attribute can also be accessed via IDL:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>// This sets the IDREF for the anchor element, and not the element itself:</span></span>
<span class="line"><span>myPopover.anchor </span><span>=</span><span> idref</span></span></code></pre>
<p>Akin to modal <code>&lt;dialog&gt;</code> and fullscreen elements, popovers allow access to a <code>::backdrop</code> pseudo element, which is a full-screen element placed directly behind the popover in the top layer. This allows the developer to do things like blur out the background when a popover is showing:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>div</span><span> popover</span><span>&gt;I'm a popover&lt;/</span><span>div</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>style</span><span>&gt;</span></span>
<span class="line"><span>  [</span><span>popover</span><span>]</span><span>::backdrop</span><span> {</span></span>
<span class="line"><span>    backdrop-filter</span><span>: </span><span>blur</span><span>(</span><span>3</span><span>px</span><span>);</span></span>
<span class="line"><span>  }</span></span>
<span class="line"><span>&lt;/</span><span>style</span><span>&gt;</span></span></code></pre>
<p>Note that in contrast to the <code>::backdrop</code> pseudo element for modal dialogs and fullscreen elements, the <code>::backdrop</code> for a popover is styled by a UA stylesheet rule <code>pointer-events: none !important</code>, which means it cannot trap clicks outside the popover. This ensures the “click outside” light dismiss behavior continues to function. For this reason, and because <code>popover=manual</code> popovers do not have light-dismiss behavior, it is not recommended that the <code>::backdrop</code> be styled in a non-transparent way for <code>popover=manual</code> popovers. Doing so would obscure the rest of the page, while still allowing the user to click or keyboard navigate to obscured elements. In this case, a better approach might be to use a modal <code>&lt;dialog&gt;</code> element, which will trap focus within the <code>&lt;dialog&gt;</code>.</p>
<p>For elements that are displayed on the top layer via this API, there are a number of things that can cause the element to be removed from the top-layer, besides the ones <a href="#showing-and-hiding-a-popover">described above</a>. These fall into three main categories:</p>
<ul><li><strong>One at a Time.</strong> Another element being added to the top-layer causes existing top layer elements to be removed. This is typically used for “one at a time” type elements: when one popover is shown, other popovers should be hidden, so that only one is on-screen at a time. This is also used when “more important” top layer elements get added. For example, fullscreen elements should close all open popovers.</li><li><strong>Light Dismiss.</strong> User action such as clicking outside the element, hitting Escape, or causing keyboard focus to leave the element should all cause a displayed popover to be hidden. This is typically called “light dismiss”, and is discussed in more detail in <a href="#light-dismiss">this section</a>.</li><li><strong>Other Reasons.</strong> Because the top layer is a UA-managed resource, it may have other reasons (for example a user preference) to forcibly remove elements from the top layer.</li></ul>
<p>In all such cases, the UA is allowed to forcibly remove an element from the top layer and re-apply the <code>display:none</code> popover UA rule. The rules the UA uses to manage these interactions depends on the element types, and this is described in more detail in <a href="#classes-of-top-layer-ui">this section</a>.</p>
<p>The term “light dismiss” for a popover is used to describe the user “moving on” to another part of the page, or generally being done interacting with the popover. When this happens, the popover should be hidden. Several actions trigger light dismiss of a popover:</p>
<ol><li>Clicking or tapping outside the bounds of the popover. Any <code>mousedown</code> event will trigger <strong>all open popovers</strong> to be hidden, starting from the top of <a href="#the-popover-stack">the popover stack</a>, and ending with the <a href="#nearest-open-ancestral-popover">nearest open ancestral popover</a> of the <code>mousedown</code> event’s <code>target</code> <code>Node</code>. This means clicking on a popover or its trigger or anchor elements will not hide that popover.</li><li>Hitting the Escape key, or generally any <a href="#close-signal">“close signal”</a>. This will cause the topmost popover on <a href="#the-popover-stack">the popover stack</a> to be hidden.</li></ol>
<p>For <code>popover=auto</code> only, it is possible to have “nested” popovers. I.e. two popovers that are allowed to both be open at the same time, due to their relationship with each other. A simple example where this would be desired is a popover menu that contains sub-menus: it is commonly expected to support this pattern, and keep the main menu showing while the sub-menu is shown.</p>
<p>Popover nesting is not possible/applicable to the other popover types, such as <code>popover=manual</code>.</p>
<p>The <code>Document</code> contains a “stack of open popovers”, which is initially empty. When a <code>popover=auto</code> element is shown, that popover is pushed onto the top of the stack, and when a <code>popover=auto</code> element is hidden, it is popped from the top of the stack.</p>
<p>The “nearest open ancestral popover” <code>P</code> to a given <code>Node</code> N is defined in this way:</p>
<blockquote><p><code>P</code> is the topmost popover in <a href="#the-popover-stack">the popover stack</a> for which any one of the following is true:</p><ol><li><code>P</code> is a flat-tree DOM ancestor of <code>N</code>.</li><li><code>N</code> is a descendant of another popover <code>P2</code>, which has an <code>anchor</code> attribute whose value is equal to <code>P</code>’s <code>id</code> or any of <code>P</code>’s flat-tree descendant’s <code>id</code>s.</li><li><code>P</code> contains a <a href="#declarative-triggers">triggering element</a> whose target is another popover <code>P2</code>, which contains <code>N</code>.</li></ol><p>If none of the popovers in <a href="#the-popover-stack">the popover stack</a> match the above conditions, then <code>P</code> is <code>null</code>.</p></blockquote>
<p>The purpose of the algorithm above is to allow “nesting” of <code>popover=auto</code> popovers in several natural ways:</p>
<ol><li><strong>Using traditional DOM tree descendants:</strong> when one popover is a descendant of another popover, these two are “nested”.</li><li><strong>Using the <code>anchor</code> attribute:</strong> when a popover has an <code>anchor</code> attribute that points to another popover (or descendant of another popover), these two are “nested”. This allows the <code>anchor</code> attribute to be used with the <a href="https://tabatkins.github.io/specs/css-anchor-position/">Anchor Positioning API</a>, transparently defining a clear “nested” relationship between the popovers. It is not necessary to use the Anchor Positioning API.</li><li><strong>Using a <a href="#declarative-triggers">declarative triggering element</a> (i.e. one using the <code>popovertarget</code> attribute):</strong> when a triggering element is contained in a popover, and can therefore trigger another popover, the second popover is “nested” within the first.</li></ol>
<p>Note that because <a href="#the-popover-stack">the popover stack</a> can only contain <code>popover=auto</code> popovers, it is only possible to “nest” popovers within <code>popover=auto</code> popovers.</p>
<p>The “close signal” <a href="https://wicg.github.io/close-watcher/#close-signal">proposal</a> attempts to unify the concept of “closing” something. Most typically, the Escape key is the standard close signal, but there are others, including the Android back button, Accessibility Tools dismiss gestures, and the Playstation square button. Any of these close signals is a light dismiss trigger for the topmost popover.</p>
<p>As described in this section, the popover types (<code>auto</code> and <code>manual</code>) each have slightly different interactions with each other. For example, <code>auto</code>s hide other <code>auto</code>s, but <code>manual</code>s do not close each other. Additionally, there are other (non-popover) elements that participate in the top layer. This section describes the general interactions between the various top layer element types, including the various flavors of popover:</p>
<ul><li>Popover (<strong><code>popover=auto</code></strong>)<ul><li>When opened, force-closes other <code>popover=auto</code>s, except for <a href="#nearest-open-ancestral-popover">ancestor popovers</a>.</li><li>It would generally be expected that a popover of this type would either receive focus, or a descendant element would receive focus when invoked.</li><li>Dismisses on <a href="https://wicg.github.io/close-watcher/#close-signal">close signal</a> or a click outside the element.</li></ul></li><li>Manual (<strong><code>popover=manual</code></strong>)<ul><li>Does not force-close any other element type.</li><li>Does not light-dismiss - closes via timer or explicit close action.</li></ul></li><li>Dialog (<strong><code>&lt;dialog&gt;.showModal()</code></strong>)<ul><li>When opened, force-closes <code>popover=auto</code>.</li><li>Dismisses on <a href="https://wicg.github.io/close-watcher/#close-signal">close signal</a></li></ul></li><li>Fullscreen (<strong><code>&lt;div&gt;.requestFullscreen()</code></strong>)<ul><li>When opened, force-closes <code>popover=auto</code>, and (with spec changes) dialog</li><li>Dismisses on <a href="https://wicg.github.io/close-watcher/#close-signal">close signal</a></li></ul></li></ul>
<p>Since the <code>popover</code> content attribute can be applied to any element, and this only impacts the element’s presentation (top layer vs not top layer), this addition does not have any direct semantic or accessibility impact. The element with the <code>popover</code> attribute will keep its existing semantics and AOM representation. For example, <code>&lt;article popover&gt;...&lt;/article&gt;</code> will continue to be exposed as an implicit <code>role=article</code>, but will be able to be displayed on top of other content. Similarly, ARIA can be used to modify accessibility mappings in <a href="https://w3c.github.io/html-aria/">the normal way</a>, for example <code>&lt;div popover role=note&gt;...&lt;/div&gt;</code>.</p>
<p>As mentioned in the <a href="#declarative-triggers">Declarative Triggers</a> section, accessibility mappings will be automatically configured to associate the popover with its trigger element, as needed.</p>
<p>While the popover API can be used on most elements, there are some limitations. It is legal to apply the <code>popover</code> attribute to a <code>&lt;dialog&gt;</code> element, for example. However, doing so causes <code>dialog.showModal()</code> (the <code>&lt;dialog&gt;</code> API to show it modally) to throw an exception. This is because it is confusing that an element with <code>popover</code> can be shown in a modal fashion. Similarly, calling <code>element.requestFullscreen()</code> on an element that has the <code>popover</code> attribute will return a rejected promise.</p>
<p>This section contains several HTML examples, showing how various UI elements might be constructed using this API.</p>
<p><strong>Note:</strong> these examples are for demonstrative purposes of how to use the <code>popovertarget</code> and <code>popover</code> attributes. They may not represent all necessary HTML, ARIA or JavaScript features needed to fully create such components.</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>button</span><span> popovertarget</span><span>=</span><span>"datepicker"</span><span>&gt;Pick a date&lt;/</span><span>button</span><span>&gt;</span></span>
<span class="line"><span>&lt;</span><span>my-date-picker</span><span> role</span><span>=</span><span>"dialog"</span><span> id</span><span>=</span><span>"datepicker"</span><span> popover</span><span>&gt;...date picker contents...&lt;/</span><span>my-date-picker</span><span>&gt;</span></span>
<span class="line"></span>
<span class="line"><span>&lt;!-- No script - the popovertarget attribute takes care of activation, and</span></span>
<span class="line"><span>     the `popover` attribute takes care of the popover behavior. --&gt;</span></span></code></pre>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>selectmenu</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>div</span><span> popover</span><span> slot</span><span>=</span><span>"listbox"</span><span> behavior</span><span>=</span><span>"listbox"</span><span>&gt;</span></span>
<span class="line"><span>    &lt;</span><span>option</span><span>&gt;Option 1&lt;/</span><span>option</span><span>&gt;</span></span>
<span class="line"><span>    &lt;</span><span>option</span><span>&gt;Option 2&lt;/</span><span>option</span><span>&gt;</span></span>
<span class="line"><span>  &lt;/</span><span>div</span><span>&gt;</span></span>
<span class="line"><span>&lt;/</span><span>selectmenu</span><span>&gt;</span></span>
<span class="line"></span>
<span class="line"><span>&lt;!-- No script - `&lt;selectmenu&gt;`'s listbox is provided by a `&lt;div popover&gt;` element,</span></span>
<span class="line"><span>     which takes care of popover behavior --&gt;</span></span></code></pre>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>div</span><span> role</span><span>=</span><span>"alert"</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>my-manual-container</span><span> popover</span><span>=</span><span>"manual"</span><span>&gt;&lt;/</span><span>my-manual-container</span><span>&gt;</span></span>
<span class="line"><span>&lt;/</span><span>div</span><span>&gt;</span></span>
<span class="line"></span>
<span class="line"><span>&lt;</span><span>script</span><span>&gt;</span></span>
<span class="line"><span>  window.</span><span>addEventListener</span><span>(</span><span>'message'</span><span>, (</span><span>e</span><span>) </span><span>=&gt;</span><span> {</span></span>
<span class="line"><span>    const</span><span> container</span><span> =</span><span> document.</span><span>querySelector</span><span>(</span><span>'my-manual-container'</span><span>)</span></span>
<span class="line"><span>    container.</span><span>appendChild</span><span>(document.</span><span>createTextNode</span><span>(</span><span>'Msg: '</span><span> +</span><span> e.data))</span></span>
<span class="line"><span>    container.</span><span>showPopover</span><span>()</span></span>
<span class="line"><span>  })</span></span>
<span class="line"><span>&lt;/</span><span>script</span><span>&gt;</span></span></code></pre>
<p>Allowing a popover/top-layer element to exceed the bounds of its containing frame poses a serious security risk: such an element could spoof browser UI or containing-page content. While the <a href="https://open-ui.org/components/popup.research.explainer-v1">original <code>&lt;popup&gt;</code> proposal</a> did not discuss this issue, the <a href="https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/ControlUICustomization/explainer.md#security"><code>&lt;selectmenu&gt;</code> proposal</a> does have a specific section at least mentioning this issue. Some top-layer APIs (e.g. the fullscreen API) make it possible for an element to exceed the frame bounds in some cases, great care must be taken in these cases to ensure user safety. Given the complete flexibility offered by the popover API (any element, arbitrary content, etc.), there would be no way to ensure the safety of this feature if it were allowed to exceed frame bounds.</p>
<p>For completeness, several use counters were added to Chromium to measure how often this type of behavior (content exceeding the frame bounds) might be needed. These are approximations, as they merely measure the total number of times one of the built-in “popover” windows, which can exceed frame bounds because of their carefully-controlled content, is shown. The popovers included in this count include the <code>&lt;select&gt;</code> popover, the <code>&lt;input type=color&gt;</code> color picker, and the <code>&lt;input type=date/etc&gt;</code> date/time picker. Data can be found here:</p>
<p>So about 11% of all popovers currently exceed their owner frame bounds. That should be considered a rough upper bound, as it is possible that some of those popovers <strong>could</strong> have fit within their frame if an attempt was made to do so, but they just happened to exceed the bounds anyway.</p>
<p>In any case, it is important to note that this API cannot be used to render content outside the containing frame.</p>
<p>Note that using the API described in this explainer, it is possible for elements contained within a shadow root to be popovers. For example, it is possible to construct a custom element that wraps a popover type UI element, such as a <code>&lt;my-popover&gt;</code>, with this DOM structure:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>my-popover</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>template</span><span> shadowroot</span><span>=</span><span>"closed"</span><span>&gt;</span></span>
<span class="line"><span>    &lt;</span><span>div</span><span> popover</span><span>=</span><span>"auto"</span><span>&gt;</span></span>
<span class="line"><span>      This is a popover:</span></span>
<span class="line"><span>      &lt;</span><span>slot</span><span>&gt;&lt;/</span><span>slot</span><span>&gt;</span></span>
<span class="line"><span>    &lt;/</span><span>div</span><span>&gt;</span></span>
<span class="line"><span>  &lt;/</span><span>template</span><span>&gt;</span></span>
<span class="line"><span>  Popover text here!</span></span>
<span class="line"><span>&lt;/</span><span>my-popover</span><span>&gt;</span></span></code></pre>
<p>In this case, the (closed) shadow root contains a <code>&lt;div&gt;</code> that has <code>popover=auto</code> and that element will be shown on the top layer when the custom element calls <code>div.showPopover()</code>.</p>
<p>This is “normal”, and the only point of this section is to point out that even shadow dom children can be promoted to the top layer, in the same way that a shadow root can contain a <code>&lt;dialog&gt;</code> that can be <code>showModal()</code>‘d, or a <code>&lt;div&gt;</code> that can be <code>requestFullscreen()</code>‘d.</p>
<p>There might come a time, sooner or later, where a new popover-type HTML element is desired which combines strong semantics and purpose-built behaviors. For example, a <code>&lt;notification&gt;</code> or <code>&lt;listbox&gt;</code> element. Those elements could be relatively easily built via the APIs proposed in this document. For example, a <code>&lt;notification&gt;</code> element could be defined to have <code>role=alert</code> and <code>popover=manual</code>, and therefore re-use this popover API for always-on-top rendering. In other words, these new elements could be <em>explained</em> in terms of the lower-level primitives being proposed for this API.</p>
<p>Many decisions and choices were made in the design of this API, and those decisions were made via numerous discussions (live and on issues) in <a href="https://open-ui.org/">OpenUI</a>, a WHATWG <a href="https://open-ui.org/working-mode">Community Group</a>.</p>
<p>To achieve the <a href="#goals">goals</a> of this project, a number of approaches could have been used:</p>
<ul><li>An HTML content attribute (this proposal).</li><li>A dedicated <code>&lt;popup&gt;</code> element.</li><li>A CSS property.</li><li>A JavaScript API.</li></ul>
<p>Each of these options is significantly different from the others. To properly evaluate them, each option was fleshed out in some detail. Please see this document for the details of that effort:</p>
<p>That document discusses the pros and cons for each alternative. After exploring these options, the <a href="#html-content-attribute">HTML content attribute</a> approach <a href="https://github.com/openui/open-ui/issues/455#issuecomment-1050172067">was resolved by OpenUI</a> to be the best overall.</p>
<p>Again, refer to the <a href="/components/popup.proposal.alternatives">Other Alternatives Considered</a> document for an exhaustive look at the other alternatives. That document runs through a fairly complete design of the other alternatives, to see what they would look like.</p>
<p>This section simply tries to summarize the primary reason that a content attribute was chosen to enable the popover behavior: a content attribute allows <em>behavior</em> to be applied to <em>any element</em>. That is useful:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>dialog</span><span> popover</span><span>=</span><span>"auto"</span><span>&gt;</span></span>
<span class="line"><span>  This is a "light dismiss" dialog</span></span>
<span class="line"><span>  &lt;</span><span>button</span><span>&gt;Ok&lt;/</span><span>button</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>button</span><span>&gt;Cancel&lt;/</span><span>button</span><span>&gt;</span></span>
<span class="line"><span>&lt;/</span><span>dialog</span><span>&gt;</span></span></code></pre>
<p>Here, the developer is building <strong>a dialog</strong>. Since HTML <a href="https://html.spec.whatwg.org/multipage/dom.html#semantics-2">strongly encourages</a> the use of the correct element that properly represents the <strong>semantics of the content</strong>, the proper element in this case is a <code>&lt;dialog&gt;</code>.</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>menu</span><span> popover</span><span>=</span><span>"auto"</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>li</span><span>&gt;&lt;</span><span>button</span><span>&gt;Item 1&lt;/</span><span>button</span><span>&gt;&lt;/</span><span>li</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>li</span><span>&gt;&lt;</span><span>button</span><span>&gt;Item 2&lt;/</span><span>button</span><span>&gt;&lt;/</span><span>li</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>li</span><span>&gt;&lt;</span><span>button</span><span>&gt;Item 3&lt;/</span><span>button</span><span>&gt;&lt;/</span><span>li</span><span>&gt;</span></span>
<span class="line"><span>&lt;/</span><span>menu</span><span>&gt;</span></span></code></pre>
<p>Similarly here, the developer is building <strong>a menu</strong>, so they should use the <code>&lt;menu&gt;</code> element. This adheres to the semantic definition of a <code>&lt;menu&gt;</code> element, and allows the content to be programmatically exposed as a listing of buttons.</p>
<p>In both cases, not only does the use of the semantically-correct element make it easier to understand the content, it also enforces the appropriate content rules and behaviors that are specific to each element. Further, using the correct element allows the UA to correctly represent the content in the accessibility tree, making assistive technologies better able to assist users in navigating the content.</p>
<p>In an alternative proposal where the popover behavior is enabled via a special element, e.g. <code>&lt;popup&gt;</code>, all of the above would need to be carefully managed by the developer via ARIA roles and attributes, as there is no single role that can consistently be used to identify a <code>&lt;popup&gt;</code> element:</p>
<pre class="astro-code github-dark" tabindex="0"><code><span class="line"><span>&lt;</span><span>popup</span><span> role</span><span>=</span><span>"dialog"</span><span>&gt;</span></span>
<span class="line"><span>  &lt;</span><span>popup</span><span> role</span><span>=</span><span>"list"</span><span>&gt;...etc...&lt;/</span><span>popup</span><span>&gt;</span></span>
<span class="line"><span>&lt;/</span><span>popup</span><span>&gt;</span></span></code></pre>
<p>and that violates the <a href="https://www.w3.org/TR/using-aria/#firstrule">first rule of ARIA</a>, which is essentially that if there’s an element that properly represents the content, use that, and don’t use ARIA.</p>
<p>By having <code>popover</code> be a content attribute that purely confers behavior upon an existing element, the above problems are nicely resolved. Semantics are provided by elements, and behaviors are confered on those elements via attributes. This situation is exactly analogous to <code>contenteditable</code> or <code>tabindex</code>, which confer specific behaviors on any element. Imagine a Web in which those two attributes were instead elements: <code>&lt;contenteditable&gt;</code> and <code>&lt;tabindex index=0&gt;</code>. In that Web, many common patterns would either be very convoluted or simply not possible.</p>
<p>Many small (and large!) behavior questions were answered via discussions at OpenUI. This section contains links to some of those:</p>
<p>Here are all non-spec-text related OpenUI popover issues, both open and closed:</p>
<p><a href="https://github.com/openui/open-ui/issues?q=is%3Aissue+label%3Apopover+-label%3Apopover-spec">https://github.com/openui/open-ui/issues?q=is%3Aissue+label%3Apopover+-label%3Apopover-spec</a></p>
<p>Here are all current, open, non-spec-text related OpenUI popover issues:</p>
<p><a href="https://github.com/openui/open-ui/issues?q=is%3Aissue+is%3Aopen+label%3Apopover+-label%3Apopover-spec+-label%3Apopover-v2">https://github.com/openui/open-ui/issues?q=is%3Aissue+is%3Aopen+label%3Apopover+-label%3Apopover-spec+-label%3Apopover-v2</a></p>
</article>


<hr>

<footer>
  <p>
    <a href="/david/" title="Aller à l’accueil"><svg class="icon icon-home">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-home"></use>
      </svg> Accueil</a> •
    <a href="/david/log/" title="Accès au flux RSS"><svg class="icon icon-rss2">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-rss2"></use>
      </svg> Suivre</a> •
    <a href="http://larlet.com" title="Go to my English profile" data-instant><svg class="icon icon-user-tie">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-user-tie"></use>
      </svg> Pro</a> •
    <a href="mailto:david%40larlet.fr" title="Envoyer un courriel"><svg class="icon icon-mail">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-mail"></use>
      </svg> Email</a> •
    <abbr class="nowrap" title="Hébergeur : Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33184162340"><svg class="icon icon-hammer2">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-hammer2"></use>
      </svg> Légal</abbr>
  </p>
  <template id="theme-selector">
      <form>
          <fieldset>
              <legend><svg class="icon icon-brightness-contrast">
                <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-brightness-contrast"></use>
              </svg> Thème</legend>
              <label>
                  <input type="radio" value="auto" name="chosen-color-scheme" checked> Auto
              </label>
              <label>
                  <input type="radio" value="dark" name="chosen-color-scheme"> Foncé
              </label>
              <label>
                  <input type="radio" value="light" name="chosen-color-scheme"> Clair
              </label>
          </fieldset>
      </form>
  </template>
</footer>
<script src="/static/david/js/instantpage-5.1.0.min.js" type="module"></script>
<script>
    function loadThemeForm(templateName) {
        const themeSelectorTemplate = document.querySelector(templateName)
        const form = themeSelectorTemplate.content.firstElementChild
        themeSelectorTemplate.replaceWith(form)

        form.addEventListener('change', (e) => {
            const chosenColorScheme = e.target.value
            localStorage.setItem('theme', chosenColorScheme)
            toggleTheme(chosenColorScheme)
        })

        const selectedTheme = localStorage.getItem('theme')
        if (selectedTheme && selectedTheme !== 'undefined') {
            form.querySelector(`[value="${selectedTheme}"]`).checked = true
        }
    }

    const prefersColorSchemeDark = '(prefers-color-scheme: dark)'
    window.addEventListener('load', () => {
        let hasDarkRules = false
        for (const styleSheet of Array.from(document.styleSheets)) {
            let mediaRules = []
            for (const cssRule of styleSheet.cssRules) {
                if (cssRule.type !== CSSRule.MEDIA_RULE) {
                    continue
                }
                // WARNING: Safari does not have/supports `conditionText`.
                if (cssRule.conditionText) {
                    if (cssRule.conditionText !== prefersColorSchemeDark) {
                        continue
                    }
                } else {
                    if (cssRule.cssText.startsWith(prefersColorSchemeDark)) {
                        continue
                    }
                }
                mediaRules = mediaRules.concat(Array.from(cssRule.cssRules))
            }

            // WARNING: do not try to insert a Rule to a styleSheet you are
            // currently iterating on, otherwise the browser will be stuck
            // in a infinite loop…
            for (const mediaRule of mediaRules) {
                styleSheet.insertRule(mediaRule.cssText)
                hasDarkRules = true
            }
        }
        if (hasDarkRules) {
            loadThemeForm('#theme-selector')
        }
    })
</script>
</body>
</html>