FF153 Popover API docs for new hint/auto popover interaction model

[hamishwillee]

The popover spec added support for some new popover hint/auto interaction in whatwg/html#12345 which will be deployed in FF1153, and likely in Chrome 150. In summary:

• Showing a hint popover doesn't hide auto popovers.
• Showing a hint popover hides non-parent hint popovers.
• Clicking outside popovers consistently hides them.
• Hiding an auto popover does not hide unrelated hint popovers.
• Showing an auto popover as a child of a hint popover downgrades the auto popover to a hint.
• Showing a popover during the show or hide of another popover is no longer allowed.

To address this I have added a summary of the auto/hint stack stuff in the using guide ## Popover open/close interaction rules and also updated the docs in various points to capture this.

@jakearchibald I would really appreciate your review of this. I've used a combination of review, testing, and chatting to Claude to work out how this works. Its the last part that concerns me - sometimes Claude makes statements that seem quite reasonable based on what you're seeing in other comments - but that miss a nuance or 10. I'll add a few inline comments too.

Related docs work can be tracked in #44461

[github-actions]

Preview URLs (5 pages)

• /en-US/docs/Web/API/HTMLElement/hidePopover
• /en-US/docs/Web/API/HTMLElement/showPopover
• /en-US/docs/Web/API/HTMLElement/togglePopover
• /en-US/docs/Web/API/Popover_API/Using
• /en-US/docs/Web/HTML/Reference/Global_attributes/popover

External URLs (3)

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

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

(comment last updated: 2026-07-03 00:36:13)

[jakearchibald]

Hope this clears things up! It's definitely a complicated feature, but it's simpler than it was previously.

[chrisdavidmills]

@hamishwillee, all seems reasonable to me. Just one small suggestion for you.

[hamishwillee]

Thanks @jakearchibald and @chrisdavidmills, I've accepted the changes and will merge. I would kind of like to have included the stack diagram you showed in https://github.com/mdn/content/pull/44603/changes#diff-0b8c2975de757a2dda2a803d20fbde1a7a7a5191123441f441816959b70f90d4R375 but I'm not sure I can do so without adding a lot more words that I am "not sure of". Best to get this in, and we might iterate in future.