Popover

An accessible popup anchored to a button.

<ui:popover.root>
    <ui:popover.trigger asChild="{true}">
        <ui:button>Open Popover</ui:button>
    </ui:popover.trigger>
    <ui:popover.content>
        <ui:popover.title>Notifications</ui:popover.title>
        <ui:popover.description>You are all caught up. Good job!</ui:popover.description>
    </ui:popover.content>
</ui:popover.root>

import { mount } from 'fluid-primitives';
import { Popover } from 'fluid-primitives/popover';

mount('popover', ({ props }) => {
    const popover = new Popover(props);
    popover.init();
    return popover;
});

Features

Focus is managed and can be trapped within the popover
Supports modal and non-modal modes
Supports custom positioning with placement options
Pressing Escape closes the popover
Automatically adjusts position to stay in viewport

Installation

typo3 ui:add popover

Read more about installing Components and Primitives.

Examples

With Close Button

Show a close button inside the popover.

<ui:popover.root>
    <ui:popover.trigger asChild="{true}">
        <ui:button>Open Popover</ui:button>
    </ui:popover.trigger>
    <ui:popover.content showCloseButton="{true}">
        <ui:popover.title>Closeable</ui:popover.title>
        <ui:popover.description>Click the X button to close.</ui:popover.description>
    </ui:popover.content>
</ui:popover.root>

Custom Positioning

Control where the popover appears relative to the trigger.

<ui:popover.root positioning="{placement: 'right'}">
    <ui:popover.trigger asChild="{true}">
        <ui:button>Open Right</ui:button>
    </ui:popover.trigger>
    <ui:popover.content>
        <ui:popover.title>Right Position</ui:popover.title>
        <ui:popover.description>This popover opens to the right.</ui:popover.description>
    </ui:popover.content>
</ui:popover.root>

Make the popover modal to trap focus and block interaction with the rest of the page.

<ui:popover.root modal="{true}">
    <ui:popover.trigger asChild="{true}">
        <ui:button>Open Modal Popover</ui:button>
    </ui:popover.trigger>
    <ui:popover.content>
        <ui:popover.title>Modal Popover</ui:popover.title>
        <ui:popover.description>Focus is trapped within this popover.</ui:popover.description>
    </ui:popover.content>
</ui:popover.root>

Localization

Default close trigger labels are shipped via XLF and follow the current Site Language. For per-template overrides, pass translated strings through the translations prop. Set closeTriggerLabel to {false} or an empty string to omit the aria-label.

<ui:popover.root
    translations="{
        closeTriggerLabel: f:translate(key: 'LLL:EXT:site_package/Resources/Private/Language/locallang.xlf:popover.close')
    }"
>
    ...
</ui:popover.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

popover.root

Provides popover state and context for the composed parts. Renders no wrapper element.

Name	Description	Required	Default
`modal`	`boolean` Whether the popover should be modal.	No	false
`portalled`	`boolean` Whether the popover is portalled and proxies tabbing behavior regardless of DOM position.	No	true
`autoFocus`	`boolean` Whether to automatically set focus on the first focusable content within the popover when opened.	No	true
`restoreFocus`	`boolean` Whether to restore focus to the element that had focus before the popover was opened.	No	true
`closeOnInteractOutside`	`boolean` Whether to close the popover when the user clicks outside of the popover.	No	true
`closeOnEscape`	`boolean` Whether to close the popover when the escape key is pressed.	No	true
`positioning`	`array` The user provided options used to position the popover content.	No	-
`defaultOpen`	`boolean` The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover.	No	-
`translations`	`array` Localized popover labels. Set entries to `` to omit the corresponding `aria-label`. Use `f:translate` for per-template localization overrides when needed.	No	-

popover.trigger

Opens and closes the popover. Renders a <button> element.

popover.positioner

Positions the popover content relative to the trigger. Renders a <div> element.

popover.content

Contains the popover panel content. Renders a <div> element.

popover.arrow

Displays a decorative arrow for the popover. Renders a <div> element.

popover.indicator

Displays a decorative state indicator. Renders a <div> element.

popover.title

Provides the accessible title for the popover. Renders a <div> element.

popover.description

Provides supporting descriptive text for the popover. Renders a <div> element.

popover.closeTrigger

Closes the popover when activated. Renders a <button> element.

Anatomy

<primitives:popover.root>
    <primitives:popover.trigger />
    <primitives:popover.positioner>
        <primitives:popover.content>
            <primitives:popover.arrow />
            <primitives:popover.closeTrigger />
            <primitives:popover.title />
            <primitives:popover.description />
        </primitives:popover.content>
    </primitives:popover.positioner>
</primitives:popover.root>