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 |
arrowPosition | "center" | "side" | Arrow position * |
arrowRadius | number | Arrow border-radius |
arrowSize | number | Arrow size |
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 |
id | string | id base to create accessibility connections |
keepMounted | boolean | If set dropdown will not be unmounted from the DOM when it is hidden, display: none styles will be added instead |
middlewares | PopoverMiddlewares | Floating ui middlewares to configure position handling |
offset | number | FloatingAxesOffsets | Default Y axis or either (main, cross, alignment) X and Y axis space between target element and dropdown |
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 |
portalProps | Omit<PortalProps, "children" | "withinPortal"> | Props to pass down to the portal when withinPortal is true |
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" | Key of theme.radius or any valid CSS value to set border-radius, theme.defaultRadius by default |
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 |
transitionProps | Partial<Omit<TransitionProps, "mounted">> | Props added to Transition component that used to animate dropdown presence, use to configure duration and animation type, { duration: 150, transition: 'fade' } by default |
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 |
shouldOverrideDefaultTargetId | boolean | Determines whether component should override default id of target element, defaults to true |
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 |