Popover

A small floating content container triggered by click or hover.

Import

import { Popover } from '@akitectio/aki-ui'

// TypeScript types
import type { 
  PopoverProps,
  PopoverRef,
  PopoverPlacement,
  PopoverTrigger 
} from '@akitectio/aki-ui'

Basic Usage

Basic Popover

import { Popover } from '@akitectio/aki-ui'

function BasicPopover() {
  return (
    <Popover
      trigger="click"
      content={
        <div>
          <h4 className="font-medium mb-2">Popover Title</h4>
          <p className="text-sm text-gray-600">
            This is a basic popover with some content.
          </p>
        </div>
      }
    >
      <button>Click me</button>
    </Popover>
  )
}

Form Popover

Popover with Form

const formContent = (
  <div className="space-y-3">
    <h4 className="font-medium">Add a comment</h4>
    <textarea
      className="w-full p-2 border border-gray-300 rounded-md text-sm resize-none"
      rows={3}
      placeholder="Write your comment here..."
    />
    <div className="flex justify-end space-x-2">
      <button className="px-3 py-1 text-sm text-gray-600">Cancel</button>
      <button className="px-3 py-1 text-sm bg-green-500 text-white rounded">
        Post
      </button>
    </div>
  </div>
)

<Popover
  trigger="click"
  placement="top-start"
  content={formContent}
  width={320}
>
  <button>Add Comment</button>
</Popover>

Information Popover

Hover for Information

User permissions
import { InformationCircleIcon } from '@heroicons/react/24/outline'

const infoContent = (
  <div className="space-y-2">
    <h4 className="font-medium">Permission Levels</h4>
    <div className="space-y-1 text-sm text-gray-600">
      <div><strong>Read:</strong> Can view content</div>
      <div><strong>Write:</strong> Can edit content</div>
      <div><strong>Admin:</strong> Can manage users and settings</div>
    </div>
  </div>
)

<div className="flex items-center space-x-2">
  <span>User permissions</span>
  <Popover
    trigger="hover"
    placement="top"
    content={infoContent}
    width={288}
  >
    <InformationCircleIcon className="h-5 w-5 text-gray-400 cursor-help" />
  </Popover>
</div>

Positioning

Different Positions

// Different placement options
<Popover placement="top" content="Top positioned">
  <button>Top</button>
</Popover>

<Popover placement="right" content="Right positioned">
  <button>Right</button>
</Popover>

<Popover placement="bottom" content="Bottom positioned">
  <button>Bottom</button>
</Popover>

<Popover placement="left" content="Left positioned">
  <button>Left</button>
</Popover>

// With alignment
<Popover placement="top-start" content="Top start">
  <button>Top Start</button>
</Popover>

<Popover placement="top-end" content="Top end">
  <button>Top End</button>
</Popover>

API Reference

PropTypeDefaultDescription
contentReactNode-Content to display in the popover
trigger'click' | 'hover' | 'focus''click'How to trigger the popover
placementPopoverPlacement'top'Position of the popover
widthnumber | string'auto'Width of the popover
maxWidthnumber | string320Maximum width of the popover
offsetnumber8Distance from trigger element
arrowbooleantrueShow arrow pointing to trigger
closeOnClickOutsidebooleantrueClose when clicking outside
closeOnEscapebooleantrueClose when pressing Escape
disabledbooleanfalseDisable the popover
onOpenfunction-Callback when popover opens
onClosefunction-Callback when popover closes

PopoverPlacement Type

type PopoverPlacement = 
  | 'top' | 'top-start' | 'top-end'
  | 'right' | 'right-start' | 'right-end'
  | 'bottom' | 'bottom-start' | 'bottom-end'
  | 'left' | 'left-start' | 'left-end'

Accessibility

  • Supports keyboard navigation (Tab, Enter, Escape)
  • ARIA attributes for screen readers (aria-describedby, role="dialog")
  • Focus management when opening/closing
  • Closes on Escape key press
  • Click outside to close functionality
  • Proper focus trapping within complex popovers
  • Respects prefers-reduced-motion for animations