Popover

A flexible component that displays rich content in a portal, triggered by a button. The content can be positioned relative to a trigger or anchor element with customizable alignment and collision handling.

Can be controlled or uncontrolled

Customize side, alignment, offsets, collision handling

Optionally render a pointing arrow

Focus is fully managed and customizable

Supports modal and non-modal modes

Example

Architecture

sc-popover-root
Slot: default
sc-popover-trigger
Slot: default You need to place an sc-button here.
sc-button
sc-popover-anchor
Slot: default
sc-popover-portal
Slot: default
sc-popover-backdrop
sc-popover-content
Slot: default Place your content here if you don't need scroll.
sc-popover-arrow
Slot: default You can place an arrow here.
sc-popover-close
Slot: default You need to place an sc-button here.
sc-button
sc-popover-scroll-area
Slot: default Place your content here if you need scroll.

Reference

  • Root

    The root container that manages the state and behavior of the popover system. Coordinates the interaction between trigger, content and optional backdrop.

    • Attributes

      • default-open
        boolean
        /
        default: false

        The initial open state of the popover when rendered. Use when you do not need to control its open state.

      • open
        boolean
        /
        default: -

        The controlled open state of the popover. Must be used in conjunction with onOpenChange.

      • modal
        boolean
        /
        default: false

        When true, interaction with elements outside the popover will be disabled and only popover content will be visible to screen readers.

    • Events

      • onOpenChange

        Event handler called when the open state of the popover changes.

  • Trigger

    A wrapper component that must contain an sc-button. The button controls the visibility of the popover content. By default, the content positions itself relative to this trigger.

    • Attributes

      • trigger-keys
        string[]
        /
        default: -

        You can define additional key codes that will trigger the popover to open.

    • Events

      • onClick

        Triggered when the sc-button in the trigger is clicked or activated via keyboard.

      • onKeydown

        Triggered on keydown of the sc-button in the trigger.

  • Anchor

    An optional element that serves as a positioning reference for the sc-popover-content. When not used, the content positions itself relative to the trigger element.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulations.

  • Portal

    Renders the backdrop and content. If position is set to fixed, the content is placed in the CSS top layer, ensuring proper stacking context and visibility above other page elements.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

      • position
        enum
        /
        default: absolute

        Determines how the popover content will be placed on the page. fixed will prevent clipping, but will slightly lag on scroll events.

  • Backdrop

    An optional overlay that renders behind the popover content. Typically used in conjunction with the modal attribute to enhance focus on the popover content.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

    • Classes

      • open

        Applied when the popover is in an open state.

      • open-transition

        Applied during the opening transition and removed when fully open.

      • close-transition

        Applied during the closing transition and removed when fully closed.

  • Content

    The container that holds the popover's content. Manages keyboard interactions, focus behavior, and positioning relative to the anchor or trigger element. Implements proper ARIA attributes for accessibility and handles collision detection with viewport boundaries.

    • Attributes

      • align
        enum
        /
        default: center

        The preferred alignment against the anchor. May adjust automatically when collisions occur.

      • align-offset
        number
        /
        default: 0

        The offset in pixels from the start or end alignment positions.

      • aria-label
        string
        /
        default: -

        Accessible label for the popover content container.

      • aria-labelled-by
        string
        /
        default: -

        Used to define the accessible label for the popover container.

      • arrow-padding
        number
        /
        default: 0

        The padding between the arrow and the edges of the content. Prevents arrow overflow with rounded corners.

      • avoid-collisions
        boolean
        /
        default: true

        When true, automatically adjusts positioning to prevent collisions with viewport boundaries.

      • close-autofocus
        boolean
        /
        default: true

        When true, returns focus to the trigger or anchor element after the popover closes.

      • collision-padding
        number
        /
        default: 0

        The distance in pixels from viewport edges where collision detection should occur. Accepts a single number or a partial padding object like {top: 20, left: 16}.

      • fallback-sides
        enum[]
        /
        default: -

        Alternative sides to try when the content doesn't fit in its primary position.

      • hide-when-detached
        boolean
        /
        default: false

        When true, hides the content when the trigger element becomes fully obscured.

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

      • match-anchor-width
        boolean
        /
        default: false

        If true, the content will have the same width as the anchor.

      • open-autofocus
        boolean
        /
        default: true

        When true, automatically focuses the first focusable element in the content when opened.

      • side
        enum
        /
        default: bottom

        The preferred side where the popover should appear relative to its anchor.

      • side-offset
        number
        /
        default: 0

        The distance in pixels between the popover and its anchor element.

      • sticky
        enum
        /
        default: partial

        Controls how the content stays within bounds. partial requires the trigger to be partially visible, while always keeps content in bounds regardless.

      • update-position-strategy
        enum
        /
        default: optimized

        Determines how often position updates occur. Use always sparingly as it updates on every animation frame.

    • Events

      • onClickOutside

        Event handler called when a click occurs outside the popover.

      • onEscapeKeydown

        Event handler called when the Escape key is pressed while the popover is active.

      • onCloseAutofocus

        Event handler called after focus is managed during popover closure.

      • onOpenAutofocus

        Event handler called after focus is managed during popover opening.

      • onOpenTransitionEnd

        Event handler called when the opening transition completes.

      • onCloseTransitionEnd

        Event handler called when the closing transition completes.

    • Classes

      • bottom

        Applied when the popover content is positioned at the bottom of the trigger.

      • bottom-in

        Applied when content is positioned at the bottom during the opening transition.

      • bottom-out

        Applied when content is positioned at the bottom during the closing transition.

      • close-transition

        Applied during the closing transition of the popover.

      • left

        Applied when the popover content is positioned to the left of the trigger.

      • left-in

        Applied when content is positioned on the left side during the opening transition.

      • left-out

        Applied when content is positioned on the left side during the closing transition.

      • open

        Applied when the popover is in an open state.

      • open-transition

        Applied during the opening transition of the popover.

      • right

        Applied when the popover content is positioned to the right of the trigger.

      • right-in

        Applied when content is positioned on the right side during the opening transition.

      • right-out

        Applied when content is positioned on the right side during the closing transition.

      • top

        Applied when the popover content is positioned at the top of the trigger.

      • top-in

        Applied when content is positioned at the top during the opening transition.

      • top-out

        Applied when content is positioned at the top during the closing transition.

  • Arrow

    An optional visual indicator that points to the anchor element. Must be rendered inside sc-popover-content. Helps visually connect the popover content with its trigger or anchor element.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying element for DOM manipulation.

    • Classes

      • bottom

        Applied when the arrow is positioned at the bottom of the popover content.

      • left

        Applied when the arrow is positioned on the left side of the popover content.

      • right

        Applied when the arrow is positioned on the right side of the popover content.

      • top

        Applied when the arrow is positioned at the top of the popover content.

  • Close

    A wrapper for an sc-button that handles popover closure. Automatically assigns appropriate ARIA roles to the button.

  • Scroll Area

    A scrollable container that allows scrolling in a popover, which is in modal mode. All scrolling outside of this container will be prevented.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying HTML element for DOM manipulation.

      • role
        string
        /
        default: -

        Optional role that is forwarded to the underlying element.

Keyboard

  • Space

    Toggles the popover open state.

  • Enter

    Toggles the popover open state.

  • Tab

    Moves focus to the next focusable element within the popover.

  • Shift+Tab

    Moves focus to the previous focusable element within the popover.

  • Escape

    Closes the popover and returns focus to the trigger or anchor element.

made for toddle