Popover | Park UI

Installation

npx @park-ui/cli add popover

Add Component

Copy the code snippet below into you components folder.

'use client'
import { ark } from '@ark-ui/react/factory'
import { Popover } from '@ark-ui/react/popover'
import type { ComponentProps } from 'react'
import { createStyleContext } from 'styled-system/jsx'
import { popover } from 'styled-system/recipes'

const { withRootProvider, withContext } = createStyleContext(popover)

export type RootProps = ComponentProps<typeof Root>
export const Root = withRootProvider(Popover.Root, {
  defaultProps: { unmountOnExit: true, lazyMount: true },
})
export const RootProvider = withRootProvider(Popover.Root, {
  defaultProps: { unmountOnExit: true, lazyMount: true },
})
export const Anchor = withContext(Popover.Anchor, 'anchor')
export const ArrowTip = withContext(Popover.ArrowTip, 'arrowTip')
export const Arrow = withContext(Popover.Arrow, 'arrow', {
  defaultProps: { children: <ArrowTip /> },
})
export const CloseTrigger = withContext(Popover.CloseTrigger, 'closeTrigger')
export const Content = withContext(Popover.Content, 'content')
export const Description = withContext(Popover.Description, 'description')
export const Indicator = withContext(Popover.Indicator, 'indicator')
export const Positioner = withContext(Popover.Positioner, 'positioner')
export const Title = withContext(Popover.Title, 'title')
export const Trigger = withContext(Popover.Trigger, 'trigger')

export const Body = withContext(ark.div, 'body')
export const Header = withContext(ark.div, 'header')
export const Footer = withContext(ark.div, 'footer')

export { PopoverContext as Context } from '@ark-ui/react/popover'

Integrate Recipe

Integrate this recipe in to your Panda config.

import { popoverAnatomy } from '@ark-ui/react/popover'
import { defineSlotRecipe } from '@pandacss/dev'

export const popover = defineSlotRecipe({
  className: 'popover',
  slots: popoverAnatomy.extendWith('header', 'body', 'footer').keys(),
  base: {
    content: {
      '--popover-bg': 'colors.gray.surface.bg',
      '--popover-padding': 'spacing.4',

      background: 'var(--popover-bg)',
      borderRadius: 'l3',
      boxShadow: 'lg',
      display: 'flex',
      flexDirection: 'column',
      maxHeight: 'var(--available-height)',
      outline: '0',
      position: 'relative',
      textStyle: 'sm',
      transformOrigin: 'var(--transform-origin)',
      width: 'xs',
      zIndex: 'calc(var(--z-index-popover) + var(--layer-index, 0))',
      _open: {
        animationStyle: 'scale-fade-in',
        animationDuration: 'fast',
      },
      _closed: {
        animationStyle: 'scale-fade-out',
        animationDuration: 'faster',
      },
    },
    title: {
      color: 'fg.default',
      fontWeight: 'medium',
      textStyle: 'md',
    },
    description: {
      color: 'fg.muted',
      textStyle: 'sm',
    },
    closeTrigger: {
      position: 'absolute',
      top: '1',
      right: '1',
    },
    header: {
      display: 'flex',
      flexDirection: 'column',
      pt: 'var(--popover-padding)',
      px: 'var(--popover-padding)',
    },
    body: { p: 'var(--popover-padding)', display: 'flex', flex: '1', flexDirection: 'column' },
    footer: {
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'flex-end',
      gap: '3',
      paddingInline: 'var(--popover-padding)',
      paddingBottom: 'var(--popover-padding)',
    },
    arrow: {
      '--arrow-size': 'sizes.3',
      '--arrow-background': 'var(--popover-bg)',
    },
    arrowTip: {
      borderTopWidth: '0.5px',
      borderInlineStartWidth: '0.5px',
    },
  },
})

Usage

import { Popover } from '@/components/ui'

<Popover.Root>
  <Popover.Trigger />
  <Popover.Positioner>
    <Popover.Content>
      <Popover.CloseTrigger />
      <Popover.Arrow>
        <Popover.ArrowTip />
      </Popover.Arrow>
      <Popover.Body>
        <Popover.Title />
      </Popover.Body>
    </Popover.Content>
  </Popover.Positioner>
</Popover.Root>

Shortcuts

The Popover provides a shortcuts for common use cases.

Arrow

The Popover.Arrow renders the Popover.ArrowTip component within in by default.

This works:

<Popover.Arrow>
  <Popover.ArrowTip />
</Popover.Arrow>

This might be more concise, if you don't need to customize the arrow tip.

<Popover.Arrow />

Examples

Controlled

Use the open and onOpenChange to control the visibility of the popover.

Lazy Mount

Use the lazyMounted and/or unmountOnExit prop to defer the mounting of the popover content until it's opened.

Placement

Use the positioning.placement prop to change the position of the popover.

Offset

Use the positioning.offset prop to adjust the position of the popover content.

Same Width

Use the positioning.sameWidth prop to make the popover content the same width as the trigger.

Nested

To use the Popover within a Popover, you need to avoid portalling the nested Popover.Positioner to the document's body.

Form

Here's an example of a popover with a form inside.

Initial Focus

Use the initialFocusEl prop to set the initial focus of the popover content.

Custom Background

Use the --popover-bg CSS variable to change the background color of the popover content and its arrow.

Within Dialog

To use the Popover within a Dialog, you need to avoid portalling the Popover.Positioner to the document's body.

If you have set scrollBehavior="inside" on the Dialog, you need to:

Set the popover positioning to fixed to avoid the popover from being clipped by the dialog.
Set hideWhenDetached to true to hide the popover when the trigger is scrolled out of view.

<Popover.Root positioning={{ strategy: "fixed", hideWhenDetached: true }}>
  {/* ... */}
</Popover.Root>

Props

Root

Prop	Default	Type
`autoFocus`	`true`	`boolean` Whether to automatically set focus on the first focusable content within the popover when opened.
`closeOnEscape`	`true`	`boolean` Whether to close the popover when the escape key is pressed.
`closeOnInteractOutside`	`true`	`boolean` Whether to close the popover when the user clicks outside of the popover.
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting
`modal`	`false`	`boolean` Whether the popover should be modal. When set to `true`: - interaction with outside elements will be disabled - only popover content will be visible to screen readers - scrolling is blocked - focus is trapped within the popover
`portalled`	`true`	`boolean` Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content.
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.
`defaultOpen`		`boolean` The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>` The ids of the elements in the popover. Useful for composition.
`immediate`		`boolean` Whether to synchronize the present change immediately or defer it to the next frame
`initialFocusEl`		`() => HTMLElement \| null` The element to focus on when the popover is opened.
`onEscapeKeyDown`		`(event: KeyboardEvent) => void` Function called when the escape key is pressed
`onExitComplete`		`VoidFunction` Function called when the animation ends in the closed state
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onOpenChange`		`(details: OpenChangeDetails) => void` Function invoked when the popover opens or closes
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onRequestDismiss`		`(event: LayerDismissEvent) => void` Function called when this layer is closed due to a parent layer being closed
`open`		`boolean` The controlled open state of the popover
`persistentElements`		`(() => Element \| null)[]` Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event
`positioning`		`PositioningOptions` The user provided options used to position the popover content
`present`		`boolean` Whether the node is present (controlled by the user)