Choosing a primitive

This page summarizes when to reach for Dialog, Popover, Tooltip, Accordion, or Collapsible, based on purpose and interaction model.

Dialog vs Popover vs Tooltip

	Dialog	Popover	Tooltip
Purpose	Modal task or confirmation	Rich interactive popup	Brief supplementary text
Modal	Yes — blocks page interaction	No — non-modal	No
Native API	<dialog> + showModal()	Popover API	None (positioned content)
Typical content	Forms, confirmations, settings	Menus, pickers, account panels	Labels, hints, shortcuts
Dismiss	Escape, close control, optional backdrop	Escape, outside press, close control	Pointer leave, Escape, blur
Focus	Trapped in the modal	Moves into content on open	Stays on trigger (hover) or moves briefly (focus)
When to choose	User must complete or cancel a task	User explores related content without leaving context	User needs a short hint without opening a panel

Accordion vs Collapsible

	Accordion	Collapsible
Purpose	Group of related disclosure items	Single independent disclosure region
Structure	Multiple items in one host	One trigger + one panel
Native option	<details> / <summary>	Button + custom panel
Grouping	Optional single-open via details[name] or data-accordion-single	No grouping — each host is independent
When to choose	FAQ lists, settings sections, filter groups	One “show more” region, sidebar section, optional detail block

Native accordion vs managed accordion

Within <pe-accordion>, choose a markup strategy:

	Native (<details>)	Managed (<div> items)
Semantics	Platform disclosure (<summary>)	Custom trigger + panel with ARIA
Animation	Optional ::details-content (browser-dependent)	Panel size variables + starting/ending style hooks
Single-open	<details name="group"> (native)	data-accordion-single on the host
When to choose	Simple structure with browser-backed disclosure behavior	Measured panel height animation is required

Choose <details> / <summary> unless measured height animation is required. See Accordion for both structures.