Editorial review: Document popover="hint" #37990

chrisdavidmills · 2025-02-06T16:59:53Z

Description

Chrome 133 supports the popover attribute hint value, which creates popovers that do not light-dismiss auto popovers when shown. This is useful for situations where, for example, you have toolbar buttons that can be pressed to show UI popovers, but you also want to reveal tooltips when the buttons are hovered, without dismissing the UI popovers.

This PR adds the HTML popover attribute hint value to the popover HTML global attribute page and the HTMLElement.popover DOM API equivalent.

It also adds a section explaining how to use popover="hint" to the Popover API "Using..." guide.

As a bonus, I've also added info about the implicit anchor references that are created between popovers (makes CSS anchor positioning easier to use with popovers).

See https://chromestatus.com/feature/5073251081912320 for the data source.

There is no reason why this can't be tech-reviewed now, but we can't merge it until the dom-examples example is reviewed and merged. I am therefore keeping this as a draft for now.

Motivation

Additional details

Related issues and pull requests

BCD: Chrome 133 supports HTML popover="hint" attribute value browser-compat-data#25864
dom-examples example addition: Add popover=hint example dom-examples#295
Add documentation of new dialog light dismiss behaviors #37196

Fixes mdn/mdn#598

github-actions · 2025-02-06T17:01:17Z

Preview URLs (14 pages)

Flaws (79)

Note! 5 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Popover_API/Using
Title: Using the Popover API
Flaw count: 8

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/inset_properties is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/API/HTMLElement
Title: HTMLElement
Flaw count: 5

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Can't resolve /en-US/docs/Web/API/HTMLElement/cancel_event

URL: /en-US/docs/Web/API/HTMLElement/showPopover
Title: HTMLElement: showPopover() method
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/HTML/Element/input
Title: <input>: The HTML Input element
Flaw count: 46

broken_links:
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Web/API/validityState/rangeOverflow is ill cased
- /en-US/docs/Web/API/validityState/tooLong is ill cased
- and 18 more flaws omitted
macros:
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Web/API/validityState/rangeOverflow which is a redirect
- Macro produces link /en-US/docs/Web/API/validityState/tooLong which is a redirect
- and 18 more flaws omitted

URL: /en-US/docs/Web/HTML/Element/button
Title: <button>: The Button element
Flaw count: 4

broken_links:
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Glossary/accessible_name is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Glossary/accessible_name which is a redirect

URL: /en-US/docs/Web/HTML/Global_attributes/popover
Title: popover
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/CSS/anchor-name
Title: anchor-name
Flaw count: 5

broken_links:
- /en-US/docs/Glossary/inset_properties is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
- Macro produces link /en-US/docs/Web/CSS/initial_value which is a redirect
- Macro produces link /en-US/docs/Web/CSS/inheritance which is a redirect
- Macro produces link /en-US/docs/Web/CSS/computed_value which is a redirect

URL: /en-US/docs/Web/CSS/CSS_anchor_positioning/Using
Title: Using CSS anchor positioning
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/inset_properties is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect

URL: /en-US/docs/Web/CSS/position-anchor
Title: position-anchor
Flaw count: 5

broken_links:
- /en-US/docs/Glossary/inset_properties is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
- Macro produces link /en-US/docs/Web/CSS/initial_value which is a redirect
- Macro produces link /en-US/docs/Web/CSS/inheritance which is a redirect
- Macro produces link /en-US/docs/Web/CSS/computed_value which is a redirect

External URLs (1)

URL: /en-US/docs/Web/API/Popover_API/Using
Title: Using the Popover API

https://mdn.github.io/dom-examples/popover-api/popover-hint/ (2 times) (Note! This may be a new URL 👀)

(comment last updated: 2025-02-19 14:21:16)

mfreed7

LGTM! Just a few small comments.

files/en-us/web/api/htmlelement/popover/index.md

files/en-us/web/api/popover_api/using/index.md

files/en-us/web/html/global_attributes/popover/index.md

files/en-us/web/api/htmlelement/popover/index.md

hamishwillee · 2025-02-13T23:07:17Z

files/en-us/web/api/popover_api/using/index.md

+This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
+
+For an example that uses this implicit association, see the [Using "hint" popover state](/en-US/docs/Web/API/Popover_API/Using#using_hint_popover_state) section above.


Just to be clear, you're saying that the implicit positioning is already in place, so you don't need to worry about it - a hint will appear in the right place above its associated element?

The first sentence doesn't quite say that "This makes it very convenient" - i.e. it sounds like something you have to do, and that you ware about to describe.

The second sentence says "for an example that uses this implicit association see ... you might say "You can see this implicit associate at work in the exmaple XXX: no special CSS had to be created to position the hints near their associated elements.

Only the association is implicit, not the positioning. The implicit association means you don't need to create an explicit anchor reference, for example using the anchor-name and position-anchor properties.

You still need to do the anchor positioning explicitly, for example, using the anchor() function as values of inset properties, or the position-area property.

I've not made much of a change here, except that I've added a link to the relevant section of the main anchor positioning guide that explains this association, and how the actual positioning is a separate step.

I've also added this link to the other pages that mention the implicit association, as I thought it would be helpful to clear up confusion.

Let me know if you think this needs anything else.

@chrisdavidmills Thanks for explaining - I get it now, but I can completely see why I made this assumption - you show no CSS.

The linked section in "For an example that uses this implicit association, see the Using "hint" popover state section above." does not provide any example. Nor does the rest of the code. Everything says there are implicit links and nothing shows how you style them.

I don't think it is enough to link to the generic styling section. We need a real example. Something like this, copied from the example source code, with explanation:

[popover="hint"] { inset: unset; position: absolute; top: calc(anchor(bottom) + 5px); justify-self: anchor-center; margin: 0; padding: 8px; border-radius: 6px; background: #271717; color: whitesmoke; box-shadow: 1px 1px 3px #999; border: none; }

I would also rename https://pr37990.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Popover_API/Using#implicit_popover_anchor_associations to "Styling hints" - but that's up to you.

I don't think styling hints makes sense as a section name fwiw, because you get implicit anchoring for auto and manual popovers too.

OK, I understand the problem now! ;-)

So, in my next commit, I have overhauled this section, explaining that you still need to add the positioning CSS code, and showing examples of what this looks like.

I have also removed the link to the earlier section about popover="hint", and just linked straight to the code example on GitHub for an actual real example, so they can just jump into the code and check it out themselves.

I think it is better to not link between these two sections, as it creates a weird circular dependency that is not really needed.

I have also added a new section earlier on in the article called "Popover accessibility features", which explains how popover/invoker relationships result in useful ARIA relationships and focus order updates.

Just to be clear you don't get the aria when the invokers are done via JS because it can be any element and we don't know that it makes sense for a given element. But you should get the focus fixup.

Ah, perfect, thanks @lukewarlow; I've adjusted my explanation to suit.

files/en-us/web/api/htmlelement/popover/index.md

files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md

files/en-us/web/api/htmlelement/showpopover/index.md

hamishwillee · 2025-02-14T00:15:31Z

files/en-us/web/api/htmlelement/togglepopover/index.md

+    - `source` {{optional_inline}}
+      - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, the control button or link associated with the popover.
+
+Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.


See https://github.com/mdn/content/pull/37990/files#r1955372659

@chrisdavidmills I'm closing all these, but once you've looked at https://github.com/mdn/content/pull/37990/files#r1958808280 you might want to link these to a fixed up section in the Using doc as an intermediate step to getting to the CSS anchor positioning doc.

I.e. "Associating anchor and positioned elements for more details on anchor references." is very general, whereas a specific example for popover hints would be very specific and make things a lot easier

Right, in my next commit, I have updated all of these bits to briefly explain all of the useful additional effects, and link to the relevant sections in the "Using..." guides. I don't want to repeat the entire explanation on each page.

files/en-us/web/api/htmlinputelement/popovertargetelement/index.md

files/en-us/web/api/popover_api/using/index.md

files/en-us/web/html/element/input/index.md

files/en-us/web/html/global_attributes/popover/index.md

hamishwillee · 2025-02-14T00:30:18Z

@chrisdavidmills Very nice. Most of the comments are duplicates

the reused wording around the implicit anchors is confusing because it reads as something you have to do, rather than something you benefit from.
There is some confusion when introducing hints between light dismiss and "auto closing". Also should be some comment about how these interact with manual popovers (I suspect they can be used in the same way, but they aren't "needed" as much because in that case you could do tooltips as a manual popover).

Co-authored-by: Hamish Willee <[email protected]>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

files/en-us/web/api/htmlelement/popover/index.md

yisibl · 2025-02-17T05:16:40Z

We should probably add some indication that Interest Invokers can be used in the future to make it trigger via hover.

https://open-ui.org/components/interest-invokers.explainer

mfreed7 · 2025-02-18T16:00:15Z

We should probably add some indication that Interest Invokers can be used in the future to make it trigger via hover.

https://open-ui.org/components/interest-invokers.explainer

I think MDN's policy is to only document things that are available in the platform, not future stuff. But I'm not positive about that.

chrisdavidmills · 2025-02-19T10:40:59Z

We should probably add some indication that Interest Invokers can be used in the future to make it trigger via hover.
https://open-ui.org/components/interest-invokers.explainer

I think MDN's policy is to only document things that are available in the platform, not future stuff. But I'm not positive about that.

That's correct. I'm aware of the interest invokers stuff, but we should save it for a separate PR, when it is implemented.

lukewarlow · 2025-02-19T11:04:36Z

files/en-us/web/api/htmlelement/showpopover/index.md

+- `options` {{optional_inline}}
+  - : An object that can contain the following properties:
+    - `source` {{optional_inline}}
+      - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, the control button or link associated with the popover.


This is possibly too restrictive language, the source can be any HTMLElement it doesn't have to be just a link or a button. Though those will be the common cases.

It doesn't even have to be the element that was clicked/hovered/etc to trigger showPopover() to be called.

Good point. In my next commit, I've updated it to just say "...that is, its control element"

lukewarlow · 2025-02-19T11:05:37Z

files/en-us/web/api/htmlelement/showpopover/index.md

+    - `source` {{optional_inline}}
+      - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, the control button or link associated with the popover.
+
+Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.


It also enables the nested popover behaviour that popovertarget/commandfor create which is worth a mention.

Can probably link to the nested popover section easy enough.

I think I'd like to leave the commandfor stuff to another PR, if that's OK. The scope creep on this one is big enough already ;-)

Can you file an issue for this?

lukewarlow · 2025-02-19T11:07:04Z

files/en-us/web/api/htmlelement/showpopover/index.md

+      - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, the control button or link associated with the popover.
+
+Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
+


It also should do a focus order fixup to put the popover next in the tab order from the source element. This is currently not implemented in Chromium. As such the Browser Compat Data should maybe be marked as a partial implementation? cc @mfreed7 to see what he thinks regarding this.

mdn/browser-compat-data#25964 - I made a BCD PR to add Safari Tech Preview as partial (due to same bug) and also marked chrome as partial. Happy to change if people think it shouldn't be partial.

I think this probably makes sense.

lukewarlow · 2025-02-19T11:08:03Z

files/en-us/web/api/htmlelement/togglepopover/index.md

+
+Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
+
+See [Associating anchor and positioned elements](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using#associating_anchor_and_positioned_elements) for more details on anchor references.


See comments on showPopover the same applies here.

all updated

lukewarlow · 2025-02-19T11:11:15Z

files/en-us/web/api/popover_api/using/index.md

@@ -190,6 +190,106 @@ There are three different ways to create nested popovers:

 See our [Nested popover menu example](https://mdn.github.io/dom-examples/popover-api/nested-popovers/) ([source](https://github.com/mdn/dom-examples/tree/main/popover-api/nested-popovers)) for an example. You'll notice that quite a few event handlers have been used to display and hide the subpopover appropriately during mouse and keyboard access, and also to hide both menus when an option is selected from either. Depending on how you handle loading of new content, either in an SPA or multi-page website, some of all of these may not be necessary, but they have been included in this demo for illustrative purposes.

+## Using "hint" popover state


I'm not sure what the policy is on documenting stuff that only applies in the middle stage where some browsers support hint but others don't. But it might be worth pointing out that popover="hint" will fallback to a manual popover in unsupporting browsers rather than auto.

I've added a quick note in my next commit. I think it's worth including, and we can always remove it when all modern browsers catch up.

lukewarlow · 2025-02-19T11:14:45Z

files/en-us/web/css/css_anchor_positioning/using/index.md

@@ -29,9 +29,9 @@ Historically, associating an element with another element and dynamically changi

 ## Associating anchor and positioned elements

-To associate an element with an anchor, you need to first declare which element is the anchor, and then specify which positioned element(s) to associate with that anchor. This can be done via CSS or via the HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute.
+To associate an element with an anchor, you need to first declare which element is the anchor, and then specify which positioned element(s) to associate with that anchor. This creates an anchor reference between the two. This association can be created explicitly via CSS or via the HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute, or in some cases, implicitly.


For a follow-up: Do we still want to document the anchor attribute? It's not shipped in any browsers and afaik doesn't seem like it will soon because the wider whatwg/csswg aren't convinced by it. This is partly what lead to popovertarget (and commandfor pointing at a popover) creating an implicit anchor relationship.

We ended up documenting the anchor attribute very early on because it was available in Canary and seemed to be a goer. If it looks like it will be killed off, I am happy to remove it. Maybe file an issue about it and wait for more definite action either way?

lukewarlow · 2025-02-19T11:17:19Z

files/en-us/web/html/global_attributes/popover/index.md

-A popover attribute can have values [`"auto"`](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss) (default) or [`"manual"`](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state).
-Popovers that have the `auto` state can be "light dismissed" by selecting outside the popover area, and generally only allow one popover to be displayed on-screen at a time.
-By contrast, `manual` popovers must always be explicitly hidden, but allow for use cases such as nested popovers in menus.
+Popovers that have the [`auto`](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss) state can be shown and hidden using associated controls (designated by the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute) and "light dismissed" by clicking outside the popover area, opening another popover, or pressing browser-specific mechanisms such as the <kbd>Esc</kbd> key.


Follow up: MIght be worth calling out commandfor alongside popovertarget in these various places?

cc @keithamus

Though perhaps a more broader pass of all mentions of popovertarget across mdn should be updated to include commandfor

Again, I'd like to do this as a separate PR.

Yeah that's absolutely fine, just wanted to note it down so it's on the radar for one of us to do. :)

…o popover=hint

lukewarlow

Non-authoritative LGTM

Document popover=hint

7363db0

chrisdavidmills requested review from a team as code owners February 6, 2025 16:59

chrisdavidmills requested review from estelle and wbamberg and removed request for a team February 6, 2025 16:59

chrisdavidmills marked this pull request as draft February 6, 2025 17:00

github-actions bot added Content:HTML Hypertext Markup Language docs Content:WebAPI Web API docs labels Feb 6, 2025

chrisdavidmills changed the title ~~Document popover=hint~~ Technical review: Document popover="hint" Feb 6, 2025

github-actions bot added the size/m [PR only] 51-500 LoC changed label Feb 6, 2025

mfreed7 reviewed Feb 11, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

files/en-us/web/api/popover_api/using/index.md Outdated Show resolved Hide resolved

files/en-us/web/html/global_attributes/popover/index.md Outdated Show resolved Hide resolved

Fixes for mfreed7 comments, added info about implicit anchor references

c7749da

github-actions bot added the Content:CSS Cascading Style Sheets docs label Feb 12, 2025

chrisdavidmills marked this pull request as ready for review February 12, 2025 15:07

chrisdavidmills requested a review from a team as a code owner February 12, 2025 15:07

chrisdavidmills requested a review from mfreed7 February 12, 2025 15:08

chrisdavidmills changed the title ~~Technical review: Document popover="hint"~~ Editorial review: Document popover="hint" Feb 12, 2025

chrisdavidmills mentioned this pull request Feb 13, 2025

Chromium 133 support for source property and implicit anchor references mdn/browser-compat-data#25909

Merged

hamishwillee reviewed Feb 13, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 13, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 13, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved