Popover
Usage
Controlled
You can control Popover state with opened and onChange props:
Controlled example with mouse events:
Controlled example with focus events:
Focus trap
If you need to use any interactive elements within Popover, set trapFocus prop:
Inline elements
Enable inline middleware to use Popover with inline elements:
Same width
Set width="target" prop to make Popover dropdown take the same width as target element:
Initial focus
Popover uses FocusTrap component to manage focus.
Add data-autofocus attribute to element that should receive initial focus:
Popover.Target children
Popover.Target requires an element or a component as a single child –
strings, fragments, numbers and multiple elements/components are not supported and will throw error.
Custom components must provide a prop to get root element ref, all Mantine components support ref out of the box.
Required ref prop
Custom components that are rendered inside Popover.Target are required to support ref prop:
Use forwardRef function to forward ref to root element:
Accessibility
Popover follows WAI-ARIA recommendations:
- Dropdown element has
role="dialog"andaria-labelledby="target-id"attributes - Target element has
aria-haspopup="dialog",aria-expanded,aria-controls="dropdown-id"attributes
Supported target elements
Uncontrolled Popover will be accessible only when used with button element or component that renders it (Button, ActionIcon, etc.).
Other elements will not support Space and Enter key presses.
Keyboard interactions
| Key | Description | Condition |
|---|---|---|
| Escape | Closes dropdown | Focus within dropdown |
| Space/Enter | Opens/closes dropdown | Focus on target element |
Popover component props
| Name | Type | Description |
|---|---|---|
| arrowOffset | number | Arrow offset in px |
| arrowPosition | "center" | "side" | Arrow position * |
| arrowRadius | number | Arrow radius in px |
| arrowSize | number | Arrow size in px |
| children * | ReactNode | Popover.Target and Popover.Dropdown components |
| clickOutsideEvents | string[] | Events that trigger outside clicks |
| closeOnClickOutside | boolean | Determines whether dropdown should be closed on outside clicks, default to true |
| closeOnEscape | boolean | Determines whether dropdown should be closed when Escape key is pressed, defaults to true |
| defaultOpened | boolean | Initial opened state for uncontrolled component |
| disabled | boolean | If set, popover dropdown will not render |
| exitTransitionDuration | number | Exit transition duration in ms |
| id | string | id base to create accessibility connections |
| middlewares | PopoverMiddlewares | Floating ui middlewares to configure position handling |
| offset | number | Space between target element and dropdown in px |
| onChange | (opened: boolean) => void | Called with current state when dropdown opens or closes |
| onClose | () => void | Called when dropdown closes |
| onOpen | () => void | Called when dropdown opens |
| onPositionChange | (position: FloatingPosition) => void | Called when dropdown position changes |
| opened | boolean | Controls dropdown opened state |
| position | "bottom" | "left" | "right" | "top" | "bottom-end" | "bottom-start" | "left-end" | "left-start" | "right-end" | "right-start" | "top-end" | "top-start" | Dropdown position relative to target |
| positionDependencies | any[] | useEffect dependencies to force update dropdown position |
| radius | number | "xs" | "sm" | "md" | "lg" | "xl" | Radius from theme.radius or number to set border-radius in px |
| returnFocus | boolean | Determines whether focus should be automatically returned to control when dropdown closes, false by default |
| shadow | MantineShadow | Key of theme.shadow or any other valid css box-shadow value |
| transition | MantineTransition | One of premade transitions ot transition object |
| transitionDuration | number | Transition duration in ms |
| trapFocus | boolean | Determines whether focus should be trapped within dropdown, default to false |
| width | PopoverWidth | Dropdown width, or 'target' to make dropdown width the same as target element |
| withArrow | boolean | Determines whether component should have an arrow |
| withRoles | boolean | Determines whether dropdown and target element should have accessible roles, defaults to true |
| withinPortal | boolean | Determines whether dropdown should be rendered within Portal, defaults to false |
| zIndex | ZIndex | Dropdown z-index |
Popover.Target component props
| Name | Type | Description |
|---|---|---|
| children * | ReactNode | Target element |
| popupType | string | Popup accessible type, 'dialog' by default |
| refProp | string | Key of the prop that should be used to get element ref |
Popover.Dropdown component props
| Name | Type | Description |
|---|---|---|
| children | ReactNode | Dropdown content |
Popover component Styles API
| Name | Static selector | Description |
|---|---|---|
| dropdown | .mantine-Popover-dropdown | Dropdown root element |
| arrow | .mantine-Popover-arrow | Dropdown arrow |