Popover

<Popover>
  <Popover.Trigger asChild>
    <Button shape="square" icon={BellIcon} />
  </Popover.Trigger>
  <Popover.Content>
    <Popover.Title>Notifications</Popover.Title>
    <Popover.Description>You are all caught up. Good job!</Popover.Description>
  </Popover.Content>
</Popover>

Installation

Barrel

import { Popover } from "@cloudflare/kumo";

Granular

import { Popover } from "@cloudflare/kumo/components/popover";

Usage

import { Popover, Button } from "@cloudflare/kumo";

export default function Example() {
  return (
    <Popover>
      <Popover.Trigger asChild>
        <Button>Open</Button>
      </Popover.Trigger>
      <Popover.Content>
        <Popover.Title>Popover Title</Popover.Title>
        <Popover.Description>
          Popover content goes here.
        </Popover.Description>
      </Popover.Content>
    </Popover>
  );
}

While popovers can be triggered on hover (using openOnHover), they serve a different purpose than tooltips. Understanding when to use each is important for accessibility and user experience.

	Tooltip	Popover
Purpose	Short, non-interactive text labels for identification	Rich, interactive content containers
Content	Plain text only	Any content: links, buttons, forms, images
Trigger	Hover or focus	Click (default) or hover
ARIA Role	`role="tooltip"`	`aria-haspopup`
Keyboard	Not focusable	Focus moves inside, traps when open

Use a Tooltip when you need to label an icon button or provide a brief explanation. Use a Popover when users need to interact with the content inside, such as clicking links, filling out forms, or dismissing with a button.

Examples

<Popover>
  <Popover.Trigger asChild>
    <Button>Open Popover</Button>
  </Popover.Trigger>
  <Popover.Content>
    <Popover.Title>Popover Title</Popover.Title>
    <Popover.Description>
      This is a basic popover with a title and description.
    </Popover.Description>
  </Popover.Content>
</Popover>

With Close Button

<Popover>
  <Popover.Trigger asChild>
    <Button>Open Settings</Button>
  </Popover.Trigger>
  <Popover.Content>
    <Popover.Title>Settings</Popover.Title>
    <Popover.Description>Configure your preferences below.</Popover.Description>
    <div className="mt-3">
      <Popover.Close asChild>
        <Button variant="secondary" size="sm">
          Close
        </Button>
      </Popover.Close>
    </div>
  </Popover.Content>
</Popover>

Positioning

Use the side prop to control where the popover appears relative to the trigger.

<Popover>
  <Popover.Trigger asChild>
    <Button>Top</Button>
  </Popover.Trigger>
  <Popover.Content side="top">
    <Popover.Title>Top</Popover.Title>
    <Popover.Description>Popover on top.</Popover.Description>
  </Popover.Content>
</Popover>

Custom Content

Popovers can contain any content, including custom layouts with avatars, buttons, and more.

<Popover>
  <Popover.Trigger asChild>
    <Button>User Profile</Button>
  </Popover.Trigger>
  <Popover.Content className="w-64">
    <div className="flex items-center gap-3">
      <div className="size-10 rounded-full bg-kumo-recessed" />
      <div>
        <Popover.Title>Jane Doe</Popover.Title>
        <p className="text-sm text-kumo-subtle">jane@example.com</p>
      </div>
    </div>
    <div className="mt-3 flex gap-2 border-t border-kumo-line pt-3">
      <Button variant="secondary" size="sm" className="flex-1">
        Profile
      </Button>
      <Popover.Close asChild>
        <Button variant="ghost" size="sm" className="flex-1">
          Sign Out
        </Button>
      </Popover.Close>
    </div>
  </Popover.Content>
</Popover>

Open on Hover

Use openOnHover on the trigger to open the popover when the user hovers over it. You can also specify a delay in milliseconds before the popover appears.

<Popover>
  <Popover.Trigger openOnHover delay={200} asChild>
    <Button variant="secondary">Hover Me</Button>
  </Popover.Trigger>
  <Popover.Content>
    <Popover.Title>Hover Triggered</Popover.Title>
    <Popover.Description>
      This popover opens on hover with a 200ms delay. It can still contain
      interactive content like buttons and links.
    </Popover.Description>
    <div className="mt-3">
      <Popover.Close asChild>
        <Button variant="secondary" size="sm">
          Got it
        </Button>
      </Popover.Close>
    </div>
  </Popover.Content>
</Popover>

API Reference

The root component that manages the popover's open state.

Prop	Type	Default	Description
side	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`	Which side of the trigger the popover appears on. - `"top"` — Above the trigger - `"bottom"` — Below the trigger - `"left"` — Left of the trigger - `"right"` — Right of the trigger