PopoverUpdated

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 for the popover. Can accept custom children or uses default close icon.
• 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 presentation="popover">...</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 presentation="popover">
      <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 presentation="popover" placement="top">
      <Popover.Arrow />
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>

Note: When using <Popover.Arrow />, you need to apply a border to Popover.Content, for instance using the border border-border class. This ensures the arrow visually connects properly with the content border.

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 presentation="popover" width={320}>
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>;

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

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

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

Bottom Sheet Presentation

Use bottom sheet presentation for mobile-optimized interaction patterns.

Important: The presentation prop on Popover.Content must match the presentation prop on Popover.Root. In development mode, a mismatch will throw an error.

<Popover presentation="bottom-sheet">
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content presentation="bottom-sheet">
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
      <Button>Close</Button>
    </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 presentation="popover" 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 presentation="popover" 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 presentation="popover">...</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 presentation="popover">
      <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
          presentation="popover"
          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>
  );
}

You can find more examples in the GitHub repository.

API Reference

Popover

AnimationRootDisableAll

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

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

Popover.Close extends CloseButton and automatically handles popover dismissal when pressed.

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 { 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.

Special Notes

Element Inspector (iOS)

Popover uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set disableFullWindowOverlay={true} on Popover.Portal. Tradeoff: the popover will not appear above native modals when disabled.