Popover is an interactive floating element that displays information related to an anchor element when the element is clicked. It represents the UI element as floating above the normal flow creating the "pop out" effect. Popover can contain a range of elements from simple strings to complex React designs.
Popover is a controlled component, it does not manage visibility state on it's own.
Popover requires a target element which acts as a pivot for the content. Popover supports multiple placement positions using which <Popover/>
element can be positioned next to the target element in any direction.
Popover comes in 3 sizes small(s)
, medium(m)
& large(l)
.
import React, { useState } from "react"
import { Popover } from "@asphalt-react/popover"
import { Button } from "@asphalt-react/button"
const App = () => {
const [open, setOpen] = useState(false)
return (
<Popover
open={open}
target={<Button>Click Me</Button>}
onOpenChange={setOpen}
>
<p>
Hello there
</p>
</Popover>
)
}
export default App
-
Popover component comes with:
- BasePopover
- FocusManager
-
BasePopover
supports 3 sizes:small(s)
,medium(m)
&large(l)
. -
FocusManager
handles the focus management for Popover content.
Use the usePopover()
hook to get all the prop getter functions and then spread them in the target & popover components. usePopover()
takes props as parameter.
React hook which returns prop getter functions. Use these functions to generate prop objects for different components in Popover.
usePopover accepts the following props:
- open
- placement
- outOfFlow
- flip
- size
- bezel
- focusTrap
- noOffset
- lowOffset
- mediumOffset
- highOffset
- onOpenChange
- stretch
Use this function to create props for Target element of the Popover.
const { getTargetProps } = usePopover({ open: true, onOpenChange: setOpen });
<Button {...getTargetProps()}>
Click me
</Button>
Use this function to create props for Popover/floating component.
const { getPopoverProps } = usePopover({ open: true, onOpenChange: setOpen });
<BasePopover {...getPopoverProps()}>
<p>
Hello there!
</p>
</BasePopover>
Use this function to create props for FocusManager
component.
const { getFocusProps } = usePopover({ open: true, onOpenChange: setOpen });
<FocusManager {...getFocusProps()}>
<BasePopover {...getPopoverProps()}>
<p>
Hello there!
</p>
</BasePopover>
<FocusManager>
import { BasePopover, usePopover, FocusManager } from "@asphalt-react/popover"
const App = () => {
const [open, setOpen] = useState(false)
const { getTargetProps, getPopoverProps, getFocusProps } = usePopover({
open,
onOpenChange: setOpen,
})
return (
<div>
<Button {...getTargetProps()}>Click me</Button>
{open && (
<FocusManager {...getFocusProps()}>
<BasePopover open={open} {...getPopoverProps()}>
<p>
Lorem ipsum dolor sit amet
</p>
</BasePopover>
</FocusManager>
)}
</div>
)
}
export default App
-
Pressing Esc key or clicking anywhere outside the popover closes it.
-
Popover traps focus within its content, rotating the focus among its interactive elements.
-
The first interactive element receives focus by default when Popover opens.
React node to render inside Popover.
type | required | default |
---|---|---|
node | true | N/A |
Target node that triggers the Popover.
type | required | default |
---|---|---|
node | true | N/A |
Decides the open state for Popover.
type | required | default |
---|---|---|
bool | false | false |
Size of the Popover.
type | required | default |
---|---|---|
enum | false | "m" |
Adds padding on all sides.
type | required | default |
---|---|---|
bool | false | true |
Placement of the Popover with respect to target node.
Popover supports multiple placements:
-
auto
•auto-start
•auto-end
-
top
•top-start
•top-end
-
bottom
•bottom-start
•bottom-end
-
left
•left-start
•left-end
-
right
•right-start
•right-end
type | required | default |
---|---|---|
enum | false | "bottom" |
The order in which focus cycles.
-
reference
- Target element which acts as pivot for Popover. -
floating
- Popover wrapper element. -
content
- Content inside Popover wrapper.
By default it's value is ['content'] - Subsequent tabs will cycle through the tabbable contents of the Popover content.
If the value is set to ['floating', 'content'] - Includes floating element in focus cycle.
If the value is set to ['reference', 'content'] - Includes reference element in focus cycle.
- If the value is set to ['reference', 'floating', 'content'] - tabs will cycle through the reference, floating & tabbable contents of the Popover content.
type | required | default |
---|---|---|
array | false | ["content"] |
Element to initially focus when Popover is opened. Can be either a number or a ref. Number is decided by the tabbable index as specified by the focusOrder.
type | required | default |
---|---|---|
union | false | 0 |
When Popover is added to a container with position: fixed
and/or overflow: hidden
,
it creates a containing block with a stacking context which the Popover can't skip.
In such scenarios, enabling outOfFlow
will remove Popover from its parent's flow.
type | required | default |
---|---|---|
bool | false | false |
Flips the position of the floating element if there is space constraint in order to make it visible in viewport.
type | required | default |
---|---|---|
bool | false | true |
Enables the Popover to stretch and fill the width of its container. By default, the Popover matches the width of its content.
Strech works only in a relatively positioned container. Refer to the example below.
type | required | default |
---|---|---|
bool | false | false |
Shifts the Popover horizontally to avoid the content from overflowing the viewport.
type | required | default |
---|---|---|
bool | false | true |
Add focus trap in the content, outside content cannot be accessed if enabled.
type | required | default |
---|---|---|
bool | false | true |
adds a low spacing between target and Popover.
type | required | default |
---|---|---|
bool | false | false |
adds a medium spacing between target and Popover.
type | required | default |
---|---|---|
bool | false | false |
adds a high spacing between target and Popover.
type | required | default |
---|---|---|
bool | false | false |
removes spacing between target and Popover.
type | required | default |
---|---|---|
bool | false | false |
callback when open state is changed.
type | required | default |
---|---|---|
func | false | null |
React node to render inside Base Popover.
type | required | default |
---|---|---|
node | true | N/A |
Indicates the open state for Popover.
type | required | default |
---|---|---|
bool | false | false |
Size of the Popover.
type | required | default |
---|---|---|
enum | false | "m" |
Adds padding on all sides.
type | required | default |
---|---|---|
bool | false | true |
Enables the Popover to stretch and fill the width of its container. By default, the Popover matches the width of its content.
type | required | default |
---|---|---|
bool | false | false |
Adds styles to position the Popover relative to the target element.
type | required | default |
---|---|---|
object | false | N/A |
React node to render inside Base Popover.
type | required | default |
---|---|---|
node | true | N/A |
context object used to focus on the floating element, pass the popoverContext
returned by the usePopover
hook.
type | required | default |
---|---|---|
object | true | N/A |
The order in which focus cycles.
-
reference
- Target element which acts as pivot for Popover. -
floating
- Popover wrapper element. -
content
- Content inside Popover wrapper.
By default it's value is ['content'] - Subsequent tabs will cycle through the tabbable contents of the Popover content.
If the value is set to ['floating', 'content'] - Includes floating element in focus cycle.
If the value is set to ['reference', 'content'] - Includes reference element in focus cycle.
- If the value is set to ['reference', 'floating', 'content'] - tabs will cycle through the reference, floating & tabbable contents of the Popover content.
type | required | default |
---|---|---|
array | false | ["content"] |
Add focus trap in the content, outside content cannot be accessed if enabled.
type | required | default |
---|---|---|
bool | false | true |
Element to initially focus when Popover is opened. Can be either a number or a ref. Number is decided by the tabbable index as specified by the focusOrder.
type | required | default |
---|---|---|
union | false | 0 |