@gravity-ui/uikit
Version:
Gravity UI base styling and components
81 lines (68 loc) • 9.47 kB
Markdown
# Popup
`Popup` positions floating content above the page, anchored to a reference element — the low-level primitive behind tooltips, popovers, and menus, built on [Floating UI](https://floating-ui.com). Its visibility is controlled with the `open` property; its children render inside the [`Portal`](./Portal.md) component unless you set the `disablePortal` property.
```tsx
import {Popup} from '@gravity-ui/uikit';
```
## Anchor
To specify the anchor of a floating element, you can use the `anchorElement` property.
```tsx
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](https://floating-ui.com/docs/flip) 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](https://floating-ui.com/docs/flip#fallbackplacements).
It is also acceptable to use the values `auto`, `auto-start`, `auto-end` to use [autoPlacement middleware](https://floating-ui.com/docs/autoPlacement) instead of flip.
## 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` | |
| container | DOM element to which component is mounted via `Portal` | `HTMLElement` | `document.body` |
| 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` | `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-radius` | Border radius |
| `--g-popup-border-width` | Border width |