HTML manual popover: keep a nonmodal panel open until a deliberate close

Decide from the browser contract

A reviewer compares a hold-code explanation with several fields in the same record. An auto popover would disappear on an outside click, which interrupts the comparison. Manual mode keeps the note visible while the reviewer works elsewhere, and an explicit button inside the panel closes it. The trigger and close button identify the same popover by ID. This is a deliberate interface choice: if a task must block the page, use a modal dialog instead; if brief help should vanish on outside interaction, use auto. A persistent nonmodal panel needs a close path that remains discoverable to keyboard and touch users.

<button type="button" popovertarget="hold-note" popovertargetaction="show">
  Show hold-code note
</button>
<section id="hold-note" popover="manual" aria-labelledby="hold-note-heading">
  <h2 id="hold-note-heading">Hold code H-47</h2>
  <p>Keep the parcel out of export until the seal review is recorded.</p>
  <button type="button" popovertarget="hold-note" popovertargetaction="hide">
    Close note
  </button>
</section>

Cost and verification

Native show and hide avoid a custom click-away listener, though the panel still needs positioning and overlap checks on small screens. The markup does not store the reviewer's decision or enforce a hold on the server; those are separate application contracts. Test focus movement, Escape expectations, outside clicks, and access to the close button on supported browsers. If the panel must persist across navigation, that persistence needs explicit application state and should be communicated to users rather than inferred from the attribute.

Common Mistakes

• Do not expect outside clicks to close a manual popover.
• Do not omit an obvious close control.
• Do not use a nonmodal popover for a blocking confirmation.

Connected lessons

• HTML popover: show dismissible nonmodal help with a button
• HTML dialog versus popover: decide whether the task blocks the page
• HTML focus order: use native controls and keep DOM order usable

Continue with HTML dialog closedby: choose whether outside clicks dismiss a panel.

Related CSS decisions

• CSS :popover-open: style only the visible popover state