mirror of
https://github.com/nextui-org/nextui.git
synced 2025-12-08 19:26:11 +00:00
baec55029d
* chore(root): menu and select components in progress * chore(root): merged with main * feat(menu): stories created * feat(dropdown): menu migrated to menu component * feat(select): base implementation in progress * feat(select): listbox implemented * feat(select): scroll overflow and auto scroll added * feat(select): colors & variants improved, inside placement complete, outside pending * feat(scroll-shadow): new component in progress * feat(select): scroll shadow integrated * fix(select): popover implementation, more scroll shadow stories added * feat(listbox): custom styles example added to stories * chore(listbox): overflow hidden removed * feat(select): variants and styles completed * chore(select): description story added * feat(select): more stories added * fix(select): dynamic collections inference, styles improved, more stories added * fix(select): auto scroll to selected item, scroll padding added * chore(select): scroll behavior changed to nearest * feat(select): custom item story added * fix(select): autoscroll fixed * feat(select): multi select support added * feat(select): more examples added, clean-package modified to remove dev packages * chore(modal): useImperativeHandle removed * feat(select): render value story improved * feat(docs): listbox & scroll shadow docs done * feat(docs): select documentation in progress * fix: select aria label (#1425) * feat(docs): more examples added * feat(docs): select multiple added, storybook favicon changed * fix: added value to aria label of select (#1431) * feat(select): more examples added, storybook favicon changed * fix(popover): dialog role removed * feat(select): api added, async loading exampled added * fix: fixed list box on click not working with sr click (#1439) * feat(select): async items loading support added and documented * feat(root): input styles updated to be as the select ones * chore(root): listbox and scroll shadow readme updated * feat(select): ts examples added, banner updated * fix(popover): voiceover closes when focusing an item fixed * chore(select): focus scope removed * fix(popover): free solo popover added to use without a trigger * feat(select): blog post added * chore(docs): search meta generated, multi controlled onchange example fixed * chore(root): changeset added --------- Co-authored-by: Jakob Guddas <github@jguddas.de>
222 lines
16 KiB
Plaintext
222 lines
16 KiB
Plaintext
---
|
||
title: "Popover"
|
||
description: "Popover is a non-modal dialog that floats around its disclosure. It's commonly used for displaying additional rich content on top of something."
|
||
---
|
||
|
||
import {popoverContent} from "@/content/components/popover";
|
||
|
||
# Popover
|
||
|
||
Popover is a **non-modal** dialog that floats around its disclosure. It's commonly used for displaying
|
||
additional rich content on top of something.
|
||
|
||
<ComponentLinks component="popover" reactAriaHook="usePopover" />
|
||
|
||
---
|
||
|
||
<CarbonAd/>
|
||
|
||
## Import
|
||
|
||
NextUI exports 3 popover-related components:
|
||
|
||
- **Popover**: The main component to display a popover.
|
||
- **PopoverTrigger**: The component that triggers the popover.
|
||
- **PopoverContent**: The component that contains the popover content.
|
||
|
||
<ImportTabs
|
||
commands={{
|
||
main: 'import {Popover, PopoverTrigger, PopoverContent} from "@nextui-org/react";',
|
||
individual: 'import {Popover, PopoverTrigger, PopoverContent} from "@nextui-org/popover";',
|
||
}}
|
||
/>
|
||
|
||
## Usage
|
||
|
||
<CodeDemo title="Usage" files={popoverContent.usage} />
|
||
|
||
### With Arrow
|
||
|
||
<CodeDemo title="With Arrow" files={popoverContent.arrow} />
|
||
|
||
### Colors
|
||
|
||
<CodeDemo title="Colors" files={popoverContent.colors} />
|
||
|
||
### Placements
|
||
|
||
<CodeDemo title="Placements" files={popoverContent.placements} />
|
||
|
||
### Offset
|
||
|
||
<CodeDemo title="Offset" files={popoverContent.offset} />
|
||
|
||
### Controlled
|
||
|
||
<CodeDemo title="Controlled" files={popoverContent.controlled} />
|
||
|
||
### Title Props
|
||
|
||
To be sure that the popover exposes the correct title to assistive technologies, you should use the
|
||
`titleProps` prop on the `PopoverContent` component. To use this prop, you must pass a function as a child.
|
||
|
||
<CodeDemo title="Title Props" files={popoverContent.titleProps} />
|
||
|
||
### With Form
|
||
|
||
The `Popover` handles the focus within the popover content. It means that you can use the popover with
|
||
form elements without any problem. the focus returns to the trigger when the popover closes.
|
||
|
||
<CodeDemo title="With Form" files={popoverContent.withForm} />
|
||
|
||
> **Note**: You can add the `autoFocus` prop to the first `Input` component to focus it when the popover opens.
|
||
|
||
### Backdrop
|
||
|
||
The `Popover` component has a `backdrop` prop to show a backdrop behind the popover. The backdrop can be
|
||
either `transparent`, `opaque` or `blur`. The default value is `transparent`.
|
||
|
||
<CodeDemo title="Backdrop" files={popoverContent.backdrop} />
|
||
|
||
### Custom Motion
|
||
|
||
Popover offers a `motionProps` property to customize the `enter` / `exit` animation.
|
||
|
||
<CodeDemo title="Custom Motion" files={popoverContent.customMotion} />
|
||
|
||
> Learn more about Framer motion variants [here](https://www.framer.com/motion/animation/#variants).
|
||
|
||
### Custom Trigger
|
||
|
||
<CodeDemo title="Custom Trigger" files={popoverContent.customTrigger} />
|
||
|
||
## Slots
|
||
|
||
- **base**: The main popover slot, it wraps the popover content.
|
||
- **trigger**: The popover trigger slot, it has small styles to ensure the trigger works correctly.
|
||
- **backdrop**: The backdrop slot, it contains the backdrop styles.
|
||
- **arrow**: The arrow slot, it wraps the popover arrow, the placement of the arrow is based on the popover placement, e.g. `data-[placement=top]:...`.
|
||
|
||
### Custom Styles
|
||
|
||
You can customize the `Popover` component by passing custom Tailwind CSS classes to the component slots.
|
||
|
||
<CodeDemo title="Custom Styles" files={popoverContent.customStyles} />
|
||
|
||
<Spacer y={4} />
|
||
|
||
## Data Attributes
|
||
|
||
`Popover` has the following attributes on the `PopoverContent` element:
|
||
|
||
- **data-open**:
|
||
When the popover is open. Based on popover state.
|
||
- **data-placement**:
|
||
The placement of the popover. Based on `placement` prop. The arrow element is positioned based on this attribute.
|
||
- **data-focus**:
|
||
When the popover is being focused. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
|
||
- **data-focus-visible**:
|
||
When the popover is being focused with the keyboard. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
|
||
|
||
<Spacer y={4} />
|
||
|
||
## Accessibility
|
||
|
||
- The trigger and popover are automatically associated semantically via ARIA.
|
||
- Content outside the popover is hidden from assistive technologies while it is open.
|
||
- The popover closes when interacting outside, or pressing the <Kbd>Escape</Kbd> key.
|
||
- Focus is moved into the popover on mount, and restored to the trigger element on unmount.
|
||
- The popover is positioned relative to the trigger element, and automatically flips and adjusts to avoid overlapping with the edge of the browser window.
|
||
- Scrolling is prevented outside the popover to avoid unintentionally repositioning or closing it.
|
||
|
||
<Spacer y={4} />
|
||
|
||
## API
|
||
|
||
### Popover Props
|
||
|
||
| Attribute | Type | Description | Default |
|
||
| ------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
|
||
| children\* | `ReactNode[]` | The content of the popover. It's usually the `PopoverTrigger` and `PopoverContent`. | - |
|
||
| size | `sm` \| `md` \| `lg` | The popover content font size. | `md` |
|
||
| color | `default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger` | The popover color theme. | `default` |
|
||
| radius | `none` \| `sm` \| `md` \| `lg` \| `full` | The popover border radius. | `xl` |
|
||
| shadow | `none` \| `sm` \| `md` \| `lg` | The popover shadow. | `lg` |
|
||
| backdrop | `transparent` \| `opaque` \| `blur` | The popover backdrop type. | `transparent` |
|
||
| placement | [PopoverPlacement](#popover-placement) | The placement of the popover relative to its trigger reference. | `bottom` |
|
||
| state | `OverlayTriggerState` | The controlled state of the popover. See [Overlay States](https://react-spectrum.adobe.com/react-stately/useOverlayTriggerState.html#useoverlaytriggerstate) | - |
|
||
| isOpen | `boolean` | Whether the popover is open by default (controlled). | - |
|
||
| defaultOpen | `boolean` | Whether the popover is open by default (uncontrolled). | - |
|
||
| offset(px) | `number` | The distance or margin between the reference and popper. It is used internally to create an offset modifier. | `7` |
|
||
| containerPadding(px) | `number` | The placement padding that should be applied between the element and its surrounding container. | `12` |
|
||
| crossOffset(px) | `number` | The additional offset applied along the cross axis between the element and its anchor element. | `0` |
|
||
| triggerType | `dialog` \| `menu` \| `listbox` \| `tree` \| `grid`; | Type of popover that is opened by the trigger. | `dialog` |
|
||
| showArrow | `boolean` | Whether the popover should have an arrow. | `false` |
|
||
| shouldFlip | `boolean` | Whether the popover should change its placement and flip when it's about to overflow its boundary area. | `true` |
|
||
| triggerScaleOnOpen | `boolean` | Whether the trigger should scale down when the popover is open. | `true` |
|
||
| shouldBlockScroll | `boolean` | Whether to block scrolling outside the popover. | `false` |
|
||
| isKeyboardDismissDisabled | `boolean` | Whether pressing the escape key to close the popover should be disabled. | `false` |
|
||
| shouldCloseOnBlur | `boolean` | Whether the popover should close when focus is lost or moves outside it. | `false` |
|
||
| motionProps | [MotionProps](#motion-props) | The props to modify the framer motion animation. Use the `variants` API to create your own animation. | |
|
||
| portalContainer | `HTMLElement` | The container element in which the overlay portal will be placed. | `document.body` |
|
||
| triggerRef | `RefObject<HTMLElement>` | The ref for the element which the popover positions itself with respect to. | - |
|
||
| scrollRef | `RefObject<HTMLElement>` | A ref for the scrollable region within the popover. | `overlayRef` |
|
||
| disableAnimation | `boolean` | Whether the popover is animated. | `false` |
|
||
| classNames | `Record<"base"｜ "trigger"｜ "backdrop"｜ "arrow", string>` | Allows to set custom class names for the popover slots. | - |
|
||
|
||
<Spacer y={1} />
|
||
|
||
### Popover Events
|
||
|
||
| Attribute | Type | Description |
|
||
| ---------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| onOpenChange | `(isOpen: boolean) => void` | Handler that is called when the popover's open state changes. |
|
||
| shouldCloseOnInteractOutside | `(e: HTMLElement) => void` | When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the overlay ref. |
|
||
| onClose | `() => void` | Handler that is called when the popover should close. |
|
||
|
||
<Spacer y={2} />
|
||
|
||
### PopoverTrigger Props
|
||
|
||
| Attribute | Type | Description | Default |
|
||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||
| children\* | `ReactNode` | The popover trigger component, ensure the children passed is focusable. Users can tab to it using their keyboard, and it can take a ref. It is critical for accessiblity. | - |
|
||
|
||
<Spacer y={2} />
|
||
|
||
### PopoverContent Props
|
||
|
||
| Attribute | Type | Description | Default |
|
||
| --------- | ----------- | ---------------------------------------------------------- | ------- |
|
||
| children | `ReactNode` | The content that is displayed when the trigger is pressed. | - |
|
||
|
||
<Spacer y={2} />
|
||
|
||
### Popover types
|
||
|
||
<Spacer y={1} />
|
||
|
||
#### Popover Placement
|
||
|
||
```ts
|
||
type PopoverPlacement =
|
||
| "top"
|
||
| "bottom"
|
||
| "right"
|
||
| "left"
|
||
| "top-start"
|
||
| "top-end"
|
||
| "bottom-start"
|
||
| "bottom-end"
|
||
| "left-start"
|
||
| "left-end"
|
||
| "right-start"
|
||
| "right-end";
|
||
```
|
||
|
||
#### Motion Props
|
||
|
||
```ts
|
||
export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/
|
||
```
|