Popover
Display popover section relative to given target element
Import
Source
Docs
Package
Usage
Controlled
You can control Popover state with opened
and onChange
props:
Controlled example with mouse events:
Focus trap
If you need to use interactive elements (inputs, buttons, etc.) inside Popover.Dropdown
, set trapFocus
prop:
Inline elements
Enable inline
middleware to use Popover
with inline elements:
Stantler’s magnificent antlers were traded at high prices as works of art. As a result, this Pokémon was hunted close to extinction by those who were after the priceless antlers. When visiting a junkyard, you may catch sight of it having an intense fight with Murkrow over shiny objects.Ho-Oh’s feathers glow in seven colors depending on the angle at which they are struck by light. These feathers are said to bring happiness to the bearers. This Pokémon is said to live at the foot of a rainbow.
Same width
Set width="target"
prop to make Popover dropdown take the same width as target element:
offset
Set offset
prop to a number to change dropdown position relative to the target element.
This way you can control dropdown offset on main axis only.
To control offset on both axis, pass object with mainAxis
and crossAxis
properties:
Middlewares
You can enable or disable Floating UI middlewares with
middlewares
prop:
- shift middleware shifts the dropdown to keep it in view. It is enabled by default
- flip middleware changes the placement of the dropdown to keep it in view. It is enabled by default.
- inline middleware improves positioning for inline reference elements that span over multiple lines. It is disabled by default.
- size middleware manipulates dropdown size. It is disabled by default.
Example of turning off shift
and flip
middlewares:
Customize middleware options
To customize Floating UI middlewares options, pass them as
an object to the middlewares
prop. For example, to change shift
middleware padding to 20px
use the following configuration:
Dropdown arrow
Set withArrow
prop to add an arrow to the dropdown. Arrow is a div
element rotated with transform: rotate(45deg)
.
arrowPosition
prop determines how arrow is position relative to the target element when position
is set to *-start
and *-end
values on Popover
component.
By default, the value is center
– the arrow is positioned in the center of the target element if it is possible.
If you change arrowPosition
to side
, then the arrow will be positioned on the side of the target element,
and you will be able to control arrow offset with arrowOffset
prop. Note that when arrowPosition
is set to center
,
arrowOffset
prop is ignored.
Disabled
Set disabled
prop to prevent Popover.Dropdown
from rendering:
Click outside
By default, Popover
closes when you click outside of the dropdown. To disable this behavior, set closeOnClickOutside={false}
.
You can configure events that are used for click outside detection with clickOutsideEvents
prop.
By default, Popover
listens to mousedown
and touchstart
events. You can change it to any other
events, for example, mouseup
and touchend
:
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:
Nested popovers
Nested popovers require children rendering without Portal. Usually, you
should disable portal with props of the component that renders popover content, for example,
Select has comboboxProps={{ withinPortal: false }}
prop. Check documentation
of the component that you are using to render popover content to find out how to disable the portal.
If the portal is not disabled, outside click will close all popovers.
Example of disabling portal in Select and DatePickerInput components:
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
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 |