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.

Text only

Tooltip

Short, non-interactive text descriptions or keyboard shortcuts. The user does not need to click anything inside.

View Tooltip docs →
Hover preview

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 →
Actions & Selection

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 →
Contextual Actions

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 →
Rich panels & Forms

Popover

Tap-driven floating panels with inputs, filters, sliders, and form controls. Supports both non-modal and modal focus trapping.

View Popover docs →
Full-focus & Alerts

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.

PropertyTooltipHovercardDropdownContext MenuPopoverModal
TriggerHover / focusHover / focusClick / Enter / SpaceRight-click / Long-press / Shift+F10Click / TapExplicit open() / Click
ARIA Roletooltipdialogmenumenudialogdialog / alertdialog
A11y Linkaria-describedbyaria-haspopup="dialog"aria-haspopup="menu"aria-haspopup="menu"aria-haspopup="dialog"aria-haspopup="dialog" / aria-labelledby
Focus ModelNever entersTab moves insideRoving tabindexRoving tabindexInteractive / AutofocusStrict focus trap
Keyboard NavNone (reading only)Sequential Tab orderArrows + Typeahead (500ms)Arrows + Typeahead (500ms)Tab order / Modal trapTab trap cycle / Escape dismiss
ActivationNoneClickable links & buttonsEnter / Space on menuitemEnter / Space on menuitemInteractive form controlsForms, confirms, and dialog actions
Item SelectionN/AN/AAuto-closes on selectAuto-closes on selectManual or custom submitSave / Confirm / Cancel callbacks
DismissPointer leave / EscLeave corridor / Esc / BlurEsc / Click outside / SelectEsc / Click outside / Scroll / SelectEsc / Click outside / CloseEsc / Backdrop click / explicit close()
Touch SupportOff (desktop transient)Off (hover-specific)Tap to toggle menuLong-press (500ms) + HapticsPrimary click/tap triggerFull mobile touch & backdrop tap
Modal OptionNoNoNoNoYes (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" and aria-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/context-menu

Pointer-anchored secondary action tier with touch long-press and keyboard triggers.

  • Virtual Coordinate Anchor: Positions dynamically at pointer coordinates (clientX, clientY), expanding smoothly from the cursor with collision-aware flipping and edge clamping.
  • Mobile Long-press & Haptics: Detects 500ms touch holds while preserving native scrolling, with subtle haptic vibration (15ms) upon opening.
  • Keyboard Accessibility: Opens via the ContextMenu application key or Shift+F10, anchoring directly to the trigger element and focusing the first item.
  • Roving Focus: Full WAI-ARIA menu navigation with arrow keys, typeahead, Home/End, and auto-dismiss on selection or window scroll.

@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.