Popup
Maintainer:
amje
open
hasArrow
placement
import {Popup} from '@gravity-ui/uikit';
You can use a Popup to display floating content above the page. Technically, it is a wrapper around Floating UI with some default values. To manage Popup visibility, use the open property.
The Popup child components are rendered inside the Portal component. To disable this behavior, use the disablePortal property.
Anchor
To specify the anchor of a floating element, you can use the anchorElement property.
const [buttonElement, setButtonElement] = React.useState(null);
const [open, setOpen] = React.useState(false);
<Button ref={setButtonElement} onClick={() => setOpen((prevOpen) => !prevOpen)}>
Toggle Popup
</Button>
<Popup anchorElement={buttonElement} open={open} placement="bottom">
Content
</Popup>Placement
Use the placement property to manage the Popup position around the anchor element.
By default, Popup uses flip middleware to prevent overflow.
If the property is set to an array, the first element will be used as the default placement value, the rest will be used as fallback placements.
It is also acceptable to use the values auto, auto-start, auto-end to use autoPlacement middleware instead of flip.
Anchor
Top Start
Top
Top End
Right Start
Right
Right End
Bottom End
Bottom
Bottom Start
Left End
Left
Left Start
const [boxElement, setBoxElement] = React.useState(null);
<div ref={setBoxElement} />
<Popup open anchorElement={boxElement} placement="top-start">Top Start</Popup>
<Popup open anchorElement={boxElement} placement="top">Top</Popup>
<Popup open anchorElement={boxElement} placement="top-end">Top End</Popup>
<Popup open anchorElement={boxElement} placement="right-start">Right Start</Popup>
<Popup open anchorElement={boxElement} placement="right">Right</Popup>
<Popup open anchorElement={boxElement} placement="right-end">Right End</Popup>
<Popup open anchorElement={boxElement} placement="bottom-end">Bottom End</Popup>
<Popup open anchorElement={boxElement} placement="bottom">Bottom</Popup>
<Popup open anchorElement={boxElement} placement="bottom-start">Bottom Start</Popup>
<Popup open anchorElement={boxElement} placement="left-end">Left End</Popup>
<Popup open anchorElement={boxElement} placement="left">Left</Popup>
<Popup open anchorElement={boxElement} placement="left-start">Left Start</Popup>Properties
| Name | Description | Type | Default |
|---|---|---|---|
| anchorElement | Anchor element. Can also be a VirtualElement | PopupAnchorElement | |
| aria-describedby | aria-describedby attribute. Use it if you have both label and description nodes | string | |
| aria-label | aria-label attribute. Use it only if you do not have any visible caption | string | |
| aria-labelledby | aria-labelledby attribute. Preferable if you have visible caption | string | |
| children | Any React content | React.ReactNode | |
| className | class HTML attribute for the root node | string | |
| disableEscapeKeyDown | Disables triggering close on Esc | boolean | false |
| disableFocusOut | Disables triggering close on focusout | boolean | false |
| disableOutsideClick | Disables triggering close on outside clicks | boolean | false |
| disablePortal | Disables using Portal for children | boolean | false |
| disableTransition | Disables animation of popup appearing/disappearing | boolean | false |
| floatingClassName | Additional class to apply to the Floating UI element | string | |
| floatingContext | Floating UI context to provide interactions | FloatingRootContext | |
| floatingInteractions | Override Floating UI interactions | Array<ElementProps> | |
| floatingMiddlewares | Floating UI middlewares. If set, they will completely overwrite the default middlewares. | Array<Middleware> | |
| floatingStyles | Styles to apply to the Floating UI element | React.CSSProperties | |
| focusOrder | The order in which focus circle | Array<'reference' | 'floating' | 'content'> | ['content'] |
| hasArrow | Renders arrow pointing to the anchor | boolean | false |
| id | id HTML attribute | string | |
| initialFocus | Initial element to be focused. Positive number is the index of tabbable element. | number React.Ref<HTMLElement> | |
| keepMounted | Popup will not be removed from the DOM upon hiding | boolean | false |
| modal | Enables focus trapping behaviour | boolean | false |
| offset | Floating UI offset value | PopupOffset | 4 |
| onOpenChange | Handles Popup open change event | Function | |
| onTransitionIn | On start open popup animation | Function | |
| onTransitionInComplete | On finish open popup animation | Function | |
| onTransitionOut | On start close popup animation | Function | |
| onTransitionOutComplete | On finish close popup animation | Function | |
| open | Manages Popup visibility | boolean | false |
| placement | Floating UI placement | Placement Array<Placement> auto auto-start auto-end | |
| qa | Test attribute (data-qa) | string | |
| returnFocus | Element to be focused on closing | boolean React.Ref<HTMLElement> | true |
| role | Accessibility role for popup | string | |
| strategy | Floating UI positioning strategy | absolute fixed | absolute |
| style | style HTML attribute for root node | React.CSSProperties |
CSS API
| Name | Description |
|---|---|
--g-popup-background-color | Background color |
--g-popup-border-color | Border color |
--g-popup-border-width | Border width |