--- meta: title: Popup description: Popups are low-level positioning primitives used by components like dropdown and tooltip to anchor floating elements to other elements. layout: component --- Popups use [Floating UI](https://floating-ui.com/) under the hood to provide robust positioning for floating elements. The popup component exposes all of the underlying positioning features and allows you to anchor any element to any other element. Popups are designed to work with `anchor` elements and popup content. The anchor can be provided through the `anchor` attribute (by ID or element reference) or by slotting an element into the `anchor` slot. :::warning **Important:** Popup is a low-level utility component. For most use cases, you should use higher-level components like [Dropdown](/components/dropdown) or [Tooltip](/components/tooltip) instead. ::: ```html:preview ``` ## Examples ### Activating the Popup Popups are inactive by default. They won't be positioned until you add the `active` attribute. The popup logic can be computationally expensive, so only activate popups when needed. ```html:preview ``` ### External Anchors By default, anchors are slotted into the popup using the `anchor` slot. If your anchor needs to live outside of the popup, you can pass its `id`, a DOM reference, or a `VirtualElement` to the `anchor` property. ```html:preview ``` ### Placement Use the `placement` attribute to set the preferred placement of the popup. Note that the actual placement may vary to keep the popup inside the viewport when using positioning features like `flip` and `shift`. Since placement is preferred when the popup is active, the popup will use the `data-current-placement` attribute on the host element to reflect the actual placement at any given time. This allows you to style the popup based on its current placement if needed. ```html:preview ``` ### Distance Use the `distance` attribute to change the distance between the popup and its anchor. A positive value moves the popup farther away, while a negative value moves it closer. ```html:preview ``` ### Skidding Use the `skidding` attribute to move the popup along the anchor. This is useful for fine-tuning the popup's position. ```html:preview ``` ### Arrows Add an arrow to the popup with the `arrow` attribute. The arrow can be styled using the `--arrow-size` and `--arrow-color` custom properties. You can also target `::part(arrow)` in your stylesheet for additional customizations. ```html:preview ``` ### Arrow Placement Use the `arrow-placement` attribute to control how the arrow is positioned. The default is `anchor`, which aligns the arrow as close to the center of the anchor as possible. You can also use `start`, `end`, or `center` to align the arrow to the start, end, or center of the popup instead. ```html:preview ``` ### Arrow Padding Use the `arrow-padding` attribute to add padding between the arrow and the edges of the popup. This prevents the arrow from overflowing corners when the popup has a border radius. ```html:preview ``` ### Flip When the popup doesn't have enough room in its preferred placement, it can automatically flip to keep it in view. Use the `flip` attribute to enable this behavior. ```html:preview ``` ### Flip Fallback Placements When using the `flip` attribute, you can specify fallback placements using `flip-fallback-placements`. The popup will try each placement in order until it finds one that fits. ```html:preview ``` ### Flip Fallback Strategy When neither the preferred placement nor the fallback placements fit, the `flip-fallback-strategy` determines the final placement. Use `best-fit` (default) to position using the best available space, or `initial` to use the preferred placement. ```html:preview ``` ### Shift When a popup is near the edge of the viewport, part of it may be clipped. Use the `shift` attribute to move it along the axis and keep it in view. ```html:preview ``` ### Auto-size Use the `auto-size` attribute to prevent the popup from overflowing when clipped. The available width and/or height will be applied to the popup as CSS custom properties (`--auto-size-available-width` and `--auto-size-available-height`). Use these properties to set a `max-width` and/or `max-height` on the popup. ```html:preview ``` ### Sync Width and Height Use the `sync` attribute to make the popup the same width and/or height as the anchor element. This is useful for dropdowns and select controls where the popup should match the trigger's dimensions. ```html:preview ``` ### Positioning Strategy By default, popups use a `fixed` positioning strategy. This works well in most situations, but if the popup's anchor is inside a container with `overflow: auto|hidden|scroll`, the popup may be clipped. You can change the strategy to `absolute` to position the popup relative to its containing block. ```html:preview ``` ### Hover Bridge When a gap exists between the anchor and the popup, it can be difficult to interact with tooltips that show on hover. The `hover-bridge` attribute fills the gap with an invisible element, making it easier for the pointer to move from the anchor to the popup without dismissing it. ```html:preview ``` ### Virtual Elements In some cases, you may want to position the popup relative to a non-element coordinate. Virtual elements can be used for this purpose. A virtual element must contain a function called `getBoundingClientRect()` that returns a `DOMRect` object as shown below. ```html:preview ``` ## Methods ### reposition() Forces the popup to recalculate and reposition itself. This is useful when the popup's anchor or content changes dynamically. ```html:preview ``` ## Slots ### Default Slot The popup's content is placed in the default slot. ```html:preview ``` ### Anchor Slot The anchor element is placed in the `anchor` slot. ```html:preview ``` ## CSS Parts ### popup The popup container. Useful for styling or applying animations. ```html:preview ``` ### arrow The arrow element. Use this to style the arrow with custom colors or shapes. ```html:preview ``` ### hover-bridge The hover bridge element. Use this to debug or style the invisible hover bridge. ```html:preview ``` ## CSS Custom Properties ### --arrow-size Controls the size of the arrow. The default is `6px`. ```html:preview ``` ### --arrow-color Controls the color of the arrow. The default is `rgb(0, 0, 0, 0.9)`. ```html:preview ``` ### --auto-size-available-width and --auto-size-available-height When using the `auto-size` attribute, these properties are set automatically with the available width and/or height. Use them to constrain your popup content. ```html:preview ``` ## Accessibility Popups are low-level primitives and do not include built-in accessibility features. It's your responsibility to ensure proper accessibility when using popups: - Add appropriate ARIA attributes to popup content - Ensure keyboard navigation works correctly - Manage focus as needed - Use semantic HTML inside the popup For accessible overlays, consider using higher-level components like [Dropdown](/components/dropdown) or [Tooltip](/components/tooltip), which include built-in accessibility features.

Fixed (Default)

Absolute

Custom Content