Layer comparison
Every overlay has a distinct accessibility and interaction contract. Choosing the right primitive ensures predictable keyboard navigation, screen-reader semantics, and touch behavior.
How to choose
Quick decision tree based on your content and user intent.
Tooltip
Short, non-interactive text descriptions or keyboard shortcuts. The user does not need to click anything inside.
View Tooltip docs →Hovercard
Rich preview cards triggered by hovering usernames, links, or media. Users can Tab into the card to click links or follow profiles.
View Hovercard docs →Dropdown
Lists of options, sort pickers, and command menus. Focus is controlled by arrow keys, Home/End, typeahead, and selecting an item closes the menu.
View Dropdown docs →Context Menu
Secondary menus opened at pointer coordinates, touch long-press with haptics, or Shift+F10. Ideal for file rows, canvas objects, and complex item lists.
View Context Menu docs →Popover
Tap-driven floating panels with inputs, filters, sliders, and form controls. Supports both non-modal and modal focus trapping.
View Popover docs →Modal
Blocking dialogs and alerts rendered in the native Top Layer. Strict Tab focus trap, body scroll lock with layout compensation, and nested stacking.
View Modal docs →Comparison Matrix
Side-by-side technical breakdown across all six overlay primitives.
| Property | Tooltip | Hovercard | Dropdown | Context Menu | Popover | Modal |
|---|---|---|---|---|---|---|
| Trigger | Hover / focus | Hover / focus | Click / Enter / Space | Right-click / Long-press / Shift+F10 | Click / Tap | Explicit open() / Click |
| ARIA Role | tooltip | dialog | menu | menu | dialog | dialog / alertdialog |
| A11y Link | aria-describedby | aria-haspopup="dialog" | aria-haspopup="menu" | aria-haspopup="menu" | aria-haspopup="dialog" | aria-haspopup="dialog" / aria-labelledby |
| Focus Model | Never enters | Tab moves inside | Roving tabindex | Roving tabindex | Interactive / Autofocus | Strict focus trap |
| Keyboard Nav | None (reading only) | Sequential Tab order | Arrows + Typeahead (500ms) | Arrows + Typeahead (500ms) | Tab order / Modal trap | Tab trap cycle / Escape dismiss |
| Activation | None | Clickable links & buttons | Enter / Space on menuitem | Enter / Space on menuitem | Interactive form controls | Forms, confirms, and dialog actions |
| Item Selection | N/A | N/A | Auto-closes on select | Auto-closes on select | Manual or custom submit | Save / Confirm / Cancel callbacks |
| Dismiss | Pointer leave / Esc | Leave corridor / Esc / Blur | Esc / Click outside / Select | Esc / Click outside / Scroll / Select | Esc / Click outside / Close | Esc / Backdrop click / explicit close() |
| Touch Support | Off (desktop transient) | Off (hover-specific) | Tap to toggle menu | Long-press (500ms) + Haptics | Primary click/tap trigger | Full mobile touch & backdrop tap |
| Modal Option | No | No | No | No | Yes (modal: true) | Global: scroll locked; contained: local scope |
| Package | @sv-layer/tooltip | @sv-layer/hovercard | @sv-layer/dropdown | @sv-layer/context-menu | @sv-layer/popover | @sv-layer/modal |
@sv-layer/tooltip
Transient hint tier for accessibility and discoverability.
- Purely descriptive: Connected to the trigger via
aria-describedby. Screen readers announce it as additional information. - Focus never enters: Pressing Tab while a tooltip is open moves directly to the next focusable element on the page, closing the tooltip.
- Warm delay groups: Browsing adjacent toolbar icons opens tooltips instantly once the first delay has elapsed.
@sv-layer/hovercard
Non-modal preview tier with safe transit corridor.
- Semantics: Uses
role="dialog"andaria-haspopup="dialog". - SafeExit corridor: A dynamic geometric polygon connects the cursor to the card, allowing smooth diagonal mouse movement without unintended closing.
- Interactive focus: Pressing Tab immediately after hover moves focus directly into the card's interactive children.
@sv-layer/dropdown
Action menu tier with roving tabindex and keyboard navigation.
- Menu pattern: Renders with
role="menu"and automatically assignsrole="menuitem"to interactive items. - Roving tabindex: Items have
tabindex="-1"; arrow keys move active focus, preventing the menu from polluting the browser's global Tab sequence. - Typeahead search: Typing letters jumps immediately to matching options with a 500 ms buffer.
- Auto-close on select: Clicking any item closes the menu automatically.
@sv-layer/popover
General-purpose panel tier for rich forms and arbitrary controls.
- Tap-first: Opened explicitly via click or tap, making it ideal for mobile and touch devices.
- Non-modal or Modal: By default, users can freely Tab out of the popover back into the page.
With
modal: true, Tab focus is trapped inside until dismissed. - AutoFocus: Can automatically focus the first interactive field or
[autofocus]element upon opening.
@sv-layer/modal
Blocking dialog tier with native top layer, strict focus trap, and scroll lock.
- Top Layer Portal: Renders directly in the browser's native Top Layer via
popover="manual"ondocument.body, or can be localized within any container element via thecontaineroption. - Scroll Lock & Shift Compensation: Measures native scrollbar width and applies precise padding-right compensation to prevent layout jank when locking the viewport.
- Strict Focus Trap & ARIA: Cycles Tab focus exclusively within the active dialog, supports
role="dialog"androle="alertdialog", and restores focus to the trigger upon dismissal. - Multi-level Stacking: Supports nested sub-modals with hierarchical z-stacking and sequential Escape unwinding.