Popover

Import

import { Popover } from 'heroui-native';

Anatomy

<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
    </Popover.Content>
  </Popover.Portal>
</Popover>

• Popover: Main container that manages open/close state, positioning, and provides context to child components.
• Popover.Trigger: Clickable element that toggles popover visibility. Wraps any child element with press handlers.
• Popover.Portal: Renders popover content in a portal layer above other content. Ensures proper stacking and positioning.
• Popover.Overlay: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks.
• Popover.Content: Container for popover content with positioning, styling, and collision detection. Supports both popover and bottom-sheet presentations.
• Popover.Arrow: Optional arrow element pointing to the trigger. Automatically positioned based on placement.
• Popover.Close: Close button that dismisses the popover when pressed. Renders a default X icon if no children provided.
• Popover.Title: Optional title text with pre-styled typography.
• Popover.Description: Optional description text with muted styling.

Usage

Basic Usage

The Popover component uses compound parts to create floating content panels.

<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>...</Popover.Content>
  </Popover.Portal>
</Popover>

With Title and Description

Structure popover content with title and description for better information hierarchy.

<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>
      <Popover.Close />
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
    </Popover.Content>
  </Popover.Portal>
</Popover>

With Arrow

Add an arrow pointing to the trigger element for better visual connection.

<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content placement="top">
      <Popover.Arrow />
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>

Width Control

Control the width of the popover content using the width prop.

{
  /* Fixed width in pixels */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width={320}>...</Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Match trigger width */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width="trigger">...</Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Full width (100%) */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width="full">...</Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Auto-size to content (default) */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width="content-fit">...</Popover.Content>
  </Popover.Portal>
</Popover>;

Bottom Sheet Presentation

Use bottom sheet presentation for mobile-optimized interaction patterns.

<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content presentation="bottom-sheet">
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
      <Popover.Close asChild>
        <Button>Close</Button>
      </Popover.Close>
    </Popover.Content>
  </Popover.Portal>
</Popover>

Placement Options

Control where the popover appears relative to the trigger element.

<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Content placement="left">...</Popover.Content>
  </Popover.Portal>
</Popover>

Alignment Options

Fine-tune content alignment along the placement axis.

<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Content placement="top" align="start">
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>

Custom Animation

Configure custom animations for open and close transitions using the animation prop on Popover.Root.

<Popover
  animation={{
    entering: {
      type: 'spring',
      config: { damping: 15, stiffness: 300 },
    },
    exiting: {
      type: 'timing',
      config: { duration: 200 },
    },
  }}
>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>...</Popover.Content>
  </Popover.Portal>
</Popover>

Programmatic control

// Open or close popover programmatically using ref
const popoverRef = useRef<PopoverTriggerRef>(null);

// Open programmatically
popoverRef.current?.open();

// Close programmatically
popoverRef.current?.close();

// Full example
<Popover>
  <Popover.Trigger ref={popoverRef} asChild>
    <Button>Trigger</Button>
  </Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>
      <Text>Content</Text>
      <Button onPress={() => popoverRef.current?.close()}>Close</Button>
    </Popover.Content>
  </Popover.Portal>
</Popover>;

Example

import { Ionicons } from '@expo/vector-icons';
import { Button, Popover, useThemeColor } from 'heroui-native';
import { Text, View } from 'react-native';

export default function PopoverExample() {
  const themeColorMuted = useThemeColor('muted');

  return (
    <Popover>
      <Popover.Trigger asChild>
        <Button variant="tertiary" size="sm">
          <Button.StartContent>
            <Ionicons
              name="information-circle"
              size={20}
              color={themeColorMuted}
            />
          </Button.StartContent>
          <Button.LabelContent>Show Info</Button.LabelContent>
        </Button>
      </Popover.Trigger>
      <Popover.Portal>
        <Popover.Overlay />
        <Popover.Content width={320} className="gap-1 rounded-xl px-6 py-4">
          <Popover.Close className="absolute top-3 right-3 z-50" />
          <Popover.Title>Information</Popover.Title>
          <Popover.Description>
            This popover includes a title and description to provide more
            structured information to users.
          </Popover.Description>
        </Popover.Content>
      </Popover.Portal>
    </Popover>
  );
}

API Reference

Popover

PopoverRootAnimation

Animation configuration for popover root component. Can be:

• false or "disabled": Disable only root animations
• "disable-all": Disable all animations including children
• true or undefined: Use default animations
• object: Custom animation configuration

SpringAnimationConfig

TimingAnimationConfig

Popover.Trigger

Popover.Portal

Popover.Overlay

PopoverOverlayAnimation

Animation configuration for popover overlay component. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations
• object: Custom animation configuration

Popover.Content (Popover Presentation)

Popover.Content (Bottom Sheet Presentation)

PopupPopoverContentAnimation

Animation configuration for popover content component (popover presentation). Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations
• object: Custom animation configuration

Popover.Arrow

Popover.Close

PopoverCloseIconProps

Popover.Title

Popover.Description

Hooks

usePopover

Hook to access popover context values within custom components or compound components.

import { usePopover } from 'heroui-native';

const CustomContent = () => {
  const { isOpen, onOpenChange, triggerPosition } = usePopover();
  // ... your implementation
};

Returns: UsePopoverReturn

Note: This hook must be used within a Popover component. It will throw an error if called outside of the popover context.

usePopoverAnimation

Hook to access popover animation state values within custom components or compound components.

import { usePopoverAnimation } from 'heroui-native';

const CustomContent = () => {
  const { popoverState, progress, isDragging } = usePopoverAnimation();
  // ... your implementation
};

Returns: UsePopoverAnimationReturn

Note: This hook must be used within a Popover component. It will throw an error if called outside of the popover animation context.