Popover
Show content with a trigger in a floating pane.
Features
Optional arrow to point to content.
Keeps within bounds of page.
Can be placed into 12 anchor positions.
Popovers are a great way to show content that's only visible when trigger is pressed, floating above the current content.
Note: Popovers are not a recommended pattern for mobile apps, and so aren't supported on native. Instead you can use Adapt and render them as a Sheet, or just conditionally render them. We landed support for them at one point, but we need the community to contribute tests in order to support them for mobile again.
Installation
Popover is already installed in tamagui
, or you can install it independently:
yarn add @tamagui/popover
PortalProvider
When rendering into root of app instead of inline, you'll first need to install
the @tamagui/portal
package:
yarn add @tamagui/portal
Then add PortalProvider
to the root of your app:
App.tsx
import { PortalProvider } from '@tamagui/portal'import YourApp from './components/YourApp'function App() {return (<PortalProvider shouldAddRootHost><YourApp /></PortalProvider>)}export default App
Props
shouldAddRootHost
boolean
Defines whether to add a default root host or not.
Anatomy
import { Popover, Adapt } from 'tamagui' // or '@tamagui/popover'export default () => (<Popover><Popover.Trigger />{/* Optional: Control focus behavior */}<Popover.FocusScope loop trapped focusOnIdle={true}><Popover.Content><Popover.Arrow /><Popover.Close />{/* ScrollView is optional, can just put any contents inside if not scrollable */}<Popover.ScrollView>{/* ... */}</Popover.ScrollView>{/* ... */}</Popover.Content></Popover.FocusScope>{/* optionally change to sheet when small screen */}{/* you can also use <Popover.Adapt /> */}<Adapt when="maxMd"><Popover.Sheet><Popover.Sheet.Overlay /><Popover.Sheet.Frame><Popover.Sheet.ScrollView><Adapt.Contents /></Popover.Sheet.ScrollView></Popover.Sheet.Frame></Popover.Sheet></Adapt></Popover>)
API Reference
Popover
Contains every component for the popover.
Props
children (required)
React.ReactNode
Must contain Popover.Content
size
SizeTokens
Passes size down too all sub-components when set for padding, arrow, borderRadius
placement
Placement
'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'
open
boolean
defaultOpen
boolean
onOpenChange
(open: boolean) => void
keepChildrenMounted
boolean | "lazy"
By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render. The "lazy" value will only initially mount the children after a React startTransition, and then keep them mounted thereafter.
stayInFrame
ShiftProps | boolean
Keeps the Popover inside the frame, see floating-ui shift().
allowFlip
FlipProps | boolean
Moves the Popover to other sides when space allows it, see floating-ui flip().
offset
OffsetOptions
Determines the distance the Popover appears from the target, see floating-ui offset().
hoverable
boolean | UseFloatingProps
Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }
resize
SizeProps | boolean
Will set maxWidth and maxHeight of Content to fit inside outer window when it won't fit, see floating-ui size().
For most of these properties, you'll want to reference the floating-ui docs .
If using modal={true}
(which is true
by default), refer to the
PortalProvider installation for more
information.
Popover.Arrow
Popover.Arrow can be used to show an arrow that points at the Trigger element. In order for the Arrow to show you must have a Trigger element within your Popover. Arrows extend YStack, see Stacks.
Popover.Trigger
Used to trigger opening of the popover when uncontrolled, just renders a YStack, see Stacks.
Popover.Content
Extends PopperContent which extends SizableStack which extends a YStack (see Stacks).
Also extends
Used to display the content of the popover.
Props
enableAnimationForPositionChange
boolean
Disabled animate presence animations in favor of regular animation, useful for doing sliding popovers.
size
SizeTokens
Controls default padding/borderRadius when unstyled is false.
unstyled
boolean
Removes all default Tamagui styles.
trapFocus
boolean
Whether focus should be trapped within the `Popover`
disableFocusScope
boolean
Whether popover should not focus contents on open
onOpenAutoFocus
FocusScopeProps['onMountAutoFocus']
Event handler called when auto-focusing on open. Can be prevented.
onCloseAutoFocus
FocusScopeProps['onUnmountAutoFocus'] | false
Event handler called when auto-focusing on close. Can be prevented.
lazyMount
boolean
Removes all default Tamagui styles.
Popover.Anchor
Renders as YStack, see Stacks.
When you want the Trigger to be in another location from where the Popover attaches, use Anchor. When used, Anchor is where the Popover will attach, while Trigger will open it.
Popover.Sheet
When used with Adapt
, Popover will render as a sheet when that breakpoint is
active.
See Sheet for more props.
Must use Adapt.Contents
inside the Popover.Sheet.Frame
to insert the
contents given to Popover.Content
Popover.FocusScope
Provides access to the underlying FocusScope component used by Popover for focus management. Can be used to control focus behavior from a parent component.
Props
enabled
boolean
Default:
true
Whether focus management is enabled
loop
boolean
Default:
false
When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable
trapped
boolean
Default:
false
When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus
focusOnIdle
boolean | number
Default:
false
When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations
onMountAutoFocus
(event: Event) => void
Event handler called when auto-focusing on mount. Can be prevented
onUnmountAutoFocus
(event: Event) => void
Event handler called when auto-focusing on unmount. Can be prevented
Popover.ScrollView
Must be nested inside Content. Renders as a plain React Native ScrollView. If
used alongside <Adapt />
and Sheet, Tamagui will automatically know to remove
this ScrollView when swapping into the Sheet, as the Sheet must use it's own
ScrollView that handles special logic for interactions with dragging.