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>

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

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>

Installation

typo3 ui:add popover

Read more about installing Components and Primitives.

Examples

Add a close button

Set showCloseButton on popover.content to add a close button in the corner.

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

Change the placement

Pass placement through the positioning prop. The popover below opens to the right of its 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>

Set modal to trap focus and block interaction with the rest of the page while the popover is open.

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

Translate the close button

The label of the close button comes from the library's language file and follows the site language. Override it per template with the translations prop:

<ui:popover.root
    translations="{
        closeTriggerLabel: f:translate(key: 'LLL:EXT:my_extension/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	false
`translations`	`array` Localized popover labels. Use `f:translate` for per-template localization overrides when needed.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true

popover.trigger

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

Name	Description	Required	Default
`value`	`string`	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-popover-trigger`	<uid>
`data-placement`	The placement of the trigger
`data-side`	The side of the trigger that the trigger is positioned on
`data-value`	The value of the item
`data-current`	Present when current
`data-state`	"open" \| "closed"

popover.positioner

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

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-popover-positioner`	<uid>
`data-nested`	Present when the positioner is nested within another {{widget}}
`data-has-nested`	Present when the positioner has nested {{widget}}s

popover.content

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

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-popover-content`	<uid>
`data-state`	"open" \| "closed"
`data-expanded`	Present when expanded
`data-placement`	The placement of the content
`data-side`	The side of the trigger that the content is positioned on
`data-nested`	popover
`data-has-nested`	popover

popover.arrow

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

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

popover.indicator

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

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-popover-indicator`	<uid>
`data-state`	"open" \| "closed"

popover.title

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

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

popover.description

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

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

popover.closeTrigger

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

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Machine JavaScript API

Name	Type	Description
`open`	`boolean`	Whether the popover is open
`setOpen`	`(open: boolean) => void`	Function to open or close the popover
`triggerValue`	`string \| null`	The trigger value
`setTriggerValue`	`(value: string \| null) => void`	Function to set the trigger value
`reposition`	`(options?: Partial<PositioningOptions>) => void`	Function to reposition the popover
`getTriggerState`	`(props?: TriggerProps) => TriggerState`	Returns the state of a specific trigger, including whether it's the currently active one
`getPositionerState`	`() => PositionerState`	Returns the state of the positioner
`getContentState`	`() => ContentState`	Returns the state of the content

Accessibility

Key	Description
`Space`	Opens/closes the popover.
`Enter`	Opens/closes the popover.
`Tab`	Moves focus to the next focusable element within the content. Note: If there are no focusable elements, focus is moved to the next focusable element after the trigger.
`Shift + Tab`	Moves focus to the previous focusable element within the content Note: If there are no focusable elements, focus is moved to the trigger.
`Esc`	Closes the popover and moves focus to the trigger.

Popover

Features

Anatomy

Installation

Examples

Add a close button

Change the placement

Make it modal

Translate the close button

API Reference

popover.root

popover.trigger

Rendered data attributes

popover.positioner

Rendered data attributes

popover.content

Rendered data attributes

popover.arrow

popover.indicator

Rendered data attributes

popover.title

popover.description

popover.closeTrigger

Machine JavaScript API

Accessibility