Popover renders its content in a floating modal. If no explicit anchor is passed via props, it anchors to its parent element by default.
import { Popover } from '@wordpress/components';
LinksPermalink to this section
View on Storybook
View source on GitHubPropsPermalink to this section
| Name | Default | Description |
|---|---|---|
animate | true |
Whether the popover should animate when opening. |
children Required |
The | |
variant | undefined |
Specifies the popover’s style. Leave undefined for the default style. Other values are:
|
anchor |
The element that should be used by the popover as its anchor. It can either
be an The anchor element should be stored in local state rather than a plain React ref to ensure reactive updating when it changes. | |
inline | false |
Whether to render the popover inline or within the slot. |
position |
Legacy way to specify the popover’s position with respect to its anchor.
Note: this prop is deprecated. Use the | |
offset | 0 |
The distance (in px) between the anchor and the popover. Pass an object to also displace the popover along its cross axis. |
onClose |
A callback invoked when the popover should be closed. | |
resize | true |
Adjusts the size of the popover to prevent its contents from going out of
view when meeting the viewport edges.
Note: The |
shift | false |
Enables the |
flip | true |
Specifies whether the popover should flip across its axis if there isn’t space for it in the normal placement. When the using a ‘top’ placement, the popover will switch to a ‘bottom’ placement. When using a ‘left’ placement, the popover will switch to a `right’ placement. The popover will retain its alignment of ‘start’ or ‘end’ when flipping. |
expandOnMobile |
Show the popover fullscreen on mobile viewports. | |
focusOnMount | 'firstElement' |
Determines focus behavior when the popover mounts.
|
headerTitle |
Used to customize the header text shown when the popover is toggled to
fullscreen on mobile viewports (see the | |
__unstableSlotName | 'Popover' |
The name of the Slot in which the popover should be rendered. It should
be also passed to the corresponding |
constrainTabbing | `focusOnMount` !== false |
Determines whether tabbing is constrained to within the popover,
preventing keyboard focus from leaving the popover content without
explicit focus elsewhere, or whether the popover remains part of the wider
tab order. If no value is passed, it will be derived from |
onFocusOutside |
A callback invoked when the focus leaves the opened popover. This should
only be provided in advanced use-cases when a popover should close under
specific circumstances (for example, if the new When not provided, the | |
noArrow | true |
Used to show/hide the arrow that points at the popover’s anchor. |
placement | 'bottom-start' |
Used to specify the popover’s position with respect to its anchor. |
__unstableForcePosition |
Prevent the popover from flipping and resizing when meeting the viewport
edges. Note: this prop is deprecated. Instead, provide use the individual
| |
anchorRect |
An object extending a | |
anchorRef |
Used to specify a fixed popover position. It can be an | |
getAnchorRect |
A function returning the same value as the one expected by the | |
isAlternate |
Used to enable a different visual style for the popover.
Note: this prop is deprecated. Use the | |
as |
The HTML element or React component to render the component as. |
ExamplesPermalink to this section
DefaultPermalink to this section
const Default = () => <Popover>(<div style={ { width: '280px', whiteSpace: 'normal' } }>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.
</div>)</Popover>;
UnstyledPermalink to this section
const Unstyled = () => <Popover variant="unstyled" />;
All PlacementsPermalink to this section
const AllPlacements = ( { children, ...args } ) => (
<div
style={ {
minWidth: '600px',
marginLeft: 'auto',
marginRight: 'auto',
} }
>
<h2>
Resize / scroll the viewport to test the behavior of the
popovers when they reach the viewport boundaries.
</h2>
<div>
{ AVAILABLE_PLACEMENTS.map( ( p ) => (
<PopoverWithAnchor
key={ p }
placement={ p }
{ ...args }
resize={ p === 'overlay' ? true : args.resize }
>
{ children }
<div>
<small>(placement: { p })</small>
</div>
</PopoverWithAnchor>
) ) }
</div>
</div>
);
Dynamic HeightPermalink to this section
const DynamicHeight = () => <Popover animate={false}>(<div
style={ {
height: 'var(--dynamic-height)',
background: '#eee',
padding: '20px',
} }
>Content with dynamic height
</div>)</Popover>;
With Slot Outside IframePermalink to this section
const WithSlotOutsideIframe = () => <PopoverInsideIframeRenderedInExternalSlot />;
With Close HandlersPermalink to this section
const WithCloseHandlers = function WithCloseHandlersStory( args ) {
const [ isVisible, setIsVisible ] = useState( false );
const buttonRef = useRef< HTMLButtonElement >( null );
const toggleVisible = ( event: React.MouseEvent ) => {
if ( buttonRef.current && event.target !== buttonRef.current ) {
return;
}
setIsVisible( ( prev ) => ! prev );
};
const handleClose = () => {
args.onClose?.();
setIsVisible( false );
};
const handleFocusOutside = ( e: React.SyntheticEvent ) => {
args.onFocusOutside?.( e );
setIsVisible( false );
};
useEffect( () => {
buttonRef.current?.scrollIntoView( {
block: 'center',
inline: 'center',
} );
}, [] );
return (
<div
style={ {
width: '300vw',
height: '300vh',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
} }
>
<Button
__next40pxDefaultSize
variant="secondary"
onClick={ toggleVisible }
ref={ buttonRef }
>
Toggle Popover
{ isVisible && (
<Popover
{ ...args }
onClose={ handleClose }
onFocusOutside={ handleFocusOutside }
>
{ args.children }
</Popover>
) }
</Button>
</div>
);
};