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 |