Popover

The Popover component provides a way to create floating overlays that display rich content in a popup. It’s perfect for tooltips, menus, forms, or any content that needs to appear above other elements without disrupting the page flow.

It can be composed with several subcomponents such as Popover.Root, Popover.Trigger, Popover.Content, and Popover.Anchor to offer a structured and customizable interface.

The Popover.Content component supports built-in title, description, and linkProps for common popover patterns, while also allowing custom content through children.

Usage

import { Popover } from "@harnessio/ui/components";

//...

return (
  <Popover.Root>
    <Popover.Trigger asChild>
      <Button>Show Info</Button>
    </Popover.Trigger>

    <Popover.Content
      title="Information"
      description="This is additional information about the feature."
    />
  </Popover.Root>

  // --- or ---

  <Popover title="Popover Title" description="Popover description" content="Popover content">
    <Button>Show Info</Button>
  </Popover>
)

Anatomy

All parts of the Popover component can be imported and composed as required.

<Popover.Root>
  <Popover.Trigger />
  <Popover.Anchor />
  <Popover.Content />
</Popover.Root>

// or

<Popover
  title="Popover Title"
  description="Popover description"
  content="Popover content"
>

Basic Popover

The simplest form of a popover with just title and description.

Popover with Custom Content

You can include any custom content inside the popover by using children.

Popover with Link

The popover supports an integrated link using the linkProps prop.

Positioning

The popover can be positioned relative to its trigger using the side and align props.

Controlled Popover

You can control the open state of the popover programmatically.

Using Anchor

The Popover.Anchor component allows you to position the popover relative to a different element than the trigger.

API Reference

Root

The Root component serves as the main container for all popover elements. It requires both a Trigger and Content as children. It can be used in either a controlled or uncontrolled manner.

<Popover.Root
  open                    // [OPTIONAL] controlled open state
  onOpenChange={onChange} // [OPTIONAL] event handler called when the open state changes
  defaultOpen             // [OPTIONAL] default open state
  modal                   // [OPTIONAL] when set to true, interaction with outside elements
                          //            will be disabled and only popover content will be
                          //            visible to screen readers.
>
  {/* Trigger, Anchor, and Content */}
</Popover.Root>

Prop	Required	Default	Type
open	false	false	boolean
onOpenChange	false		(open: boolean) => void
defaultOpen	false	false	boolean
modal	false	false	boolean
children	true		ReactNode

Trigger

The Trigger component represents the button that triggers the popover.

Accessibility

The Trigger component renders as a button by default. It is recommended to include descriptive text inside the Trigger component to allow assistive technologies to announce the button with appropriate context. If the child is solely an icon, ensure that either aria-label is provided or descriptive text is included in a hidden element.

Example

<Popover.Trigger aria-label="help information">
  <IconV2 name="help-circle" />
</Popover.Trigger>

Or

<Popover.Trigger>
  <IconV2 name="help-circle" />
  <span className="sr-only">Help information</span>
</Popover.Trigger>

<Popover.Trigger
  className="my-class" // [OPTIONAL] custom class
  asChild              // [OPTIONAL] render the trigger as the child
  disabled             // [OPTIONAL] disable the trigger
>
  {/* Trigger content */}
</Popover.Trigger>

Prop	Required	Default	Type
className	false		string
asChild	false	false	boolean
disabled	false	false	boolean
children	true		ReactNode

Content

The Content component represents the popover content with built-in support for title, description, and links.

<Popover.Content
  title="Popover Title"        // [OPTIONAL] title text
  description="Description"    // [OPTIONAL] description text
  linkProps={{                 // [OPTIONAL] link configuration
    text: "Learn more",
    href: "/docs"
  }}
  className="my-class"         // [OPTIONAL] custom class
  sideOffset={4}               // [OPTIONAL] offset from the trigger
  align="center"               // [OPTIONAL] alignment relative to trigger
  alignOffset={0}              // [OPTIONAL] offset from align
  side="bottom"                // [OPTIONAL] preferred side of the trigger
>
  {/* Custom content */}
</Popover.Content>

Prop	Required	Default	Type
title	false		string
description	false		string
linkProps	false		Omit<LinkProps, 'children'> & { text: string }
className	false		string
sideOffset	false	4	number
align	false	'center'	'start' | 'center' | 'end'
alignOffset	false	0	number
side	false	'bottom'	'top' | 'right' | 'bottom' | 'left'
children	false		ReactNode
showArrow	false	false	boolean

Anchor

The Anchor component allows you to anchor the popover to a different element than the trigger.

<Popover.Anchor
  className="my-class" // [OPTIONAL] custom class
>
  {/* Anchor element */}
</Popover.Anchor>

Prop	Required	Default	Type
className	false		string
children	false		ReactNode