Skip to main content

Popover

A floating panel component anchored to a trigger element with smart positioning, collision detection, and comprehensive accessibility features.

Live Demo​

JavaScript
<div className='popover-demo-container'>
    <Popover.Root>
      <Popover.Trigger className='popover-trigger'>
        Open Popover
      </Popover.Trigger>
      <Popover.Content className='popover-content'>
        <Popover.Arrow className='popover-arrow' />
        <div className='popover-header'>
          <span className='popover-icon'></span>
          <span className='popover-title'>Information</span>
          <Popover.Close className='popover-close'>
            <svg xmlns="http://www.w3.org/2000/svg" width="7" height="7" viewBox="0 0 7 7" fill="none">
              <path d="M6.72003 0.157674C6.51675 -0.045608 6.18837 -0.045608 5.98509 0.157674L3.43625 2.7013L0.887404 0.152461C0.684122 -0.0508205 0.355743 -0.0508205 0.152461 0.152461C-0.0508205 0.355743 -0.0508205 0.684122 0.152461 0.887404L2.7013 3.43625L0.152461 5.98509C-0.0508205 6.18837 -0.0508205 6.51675 0.152461 6.72003C0.355743 6.92331 0.684122 6.92331 0.887404 6.72003L3.43625 4.17119L5.98509 6.72003C6.18837 6.92331 6.51675 6.92331 6.72003 6.72003C6.92331 6.51675 6.92331 6.18837 6.72003 5.98509L4.17119 3.43625L6.72003 0.887404C6.9181 0.689334 6.9181 0.355743 6.72003 0.157674Z"/>
            </svg>
          </Popover.Close>
        </div>
        <p className='popover-paragraph'>Use popovers for contextual details, lightweight settings, or secondary actions without navigating away.</p>
      </Popover.Content>
    </Popover.Root>
  </div>

The live demo opens a small informational panel with a title, supporting copy, close action, and directional arrow.

Features​

  • ✅ Controlled and uncontrolled open state (open, defaultOpen, onOpenChange)
  • ✅ Floating positioning with preferred side and align
  • ✅ Automatic collision handling (flip/shift/hide middleware)
  • ✅ Portaled content rendering (document.body by default, custom container supported)
  • ✅ Dismiss behavior for pointer and focus interactions outside content
  • ✅ Optional modal mode and optional focus trap
  • ✅ Polymorphic rendering support via as prop on Trigger, Content, Arrow, and Close

Import​

import { Popover } from '@turkish-technology/spar';

Anatomy​

The Popover component is built as a compound component with multiple parts:

Parts
RootContainer managing popover state and providing context
TriggerInteractive button that toggles popover visibility
ContentFloating panel that holds the popover content
CloseOptional button to close the popover
ArrowOptional decorative arrow pointing to trigger

Structure​

<Popover.Root>
<Popover.Trigger>...</Popover.Trigger>
<Popover.Content>
<Popover.Arrow />
<Popover.Close>...</Popover.Close>
...
</Popover.Content>
</Popover.Root>

Data Flow:

  • Popover.Root owns shared state (isOpen, refs, ids, options) and exposes it through context.
  • Popover.Trigger reads context and toggles/open state while applying trigger ARIA attributes.
  • Popover.Content reads context, handles focus/dismiss behavior, computes placement, and portals the panel.
  • Popover.Close calls shared close logic from inside content.
  • Popover.Arrow reads computed placement from content context and syncs arrow positioning.

Code Examples​

Basic Popover​

Simple popover with trigger and content:

export function BasicPopover() {
return (
<Popover.Root>
<Popover.Trigger>Show Info</Popover.Trigger>
<Popover.Content>
<p>This is popover content.</p>
</Popover.Content>
</Popover.Root>
);
}

Controlled Popover​

Popover with external state control:

export function ControlledPopover() {
const [open, setOpen] = React.useState(false);

return (
<div>
<button onClick={() => setOpen(value => !value)}>External Toggle</button>

<Popover.Root open={open} onOpenChange={setOpen}>
<Popover.Trigger>Open Popover</Popover.Trigger>
<Popover.Content>
<p>Controlled content</p>
</Popover.Content>
</Popover.Root>
</div>
);
}

Modal popover. In modal mode, content is rendered with role="dialog" and focus is trapped while open:

export function ModalPopover() {
return (
<Popover.Root modal>
<Popover.Trigger>Open Modal Popover</Popover.Trigger>
<Popover.Content>
<h2>Modal Popover</h2>
<p>Focus is trapped within this popover</p>
<button>First Focusable</button>
<button>Second Focusable</button>
<Popover.Close>Close</Popover.Close>
</Popover.Content>
</Popover.Root>
);
}

Custom Positioning​

Popover with specific side and alignment preferences:

export function PositionedPopover() {
return (
<Popover.Root>
<Popover.Trigger>Top-Start Popover</Popover.Trigger>
<Popover.Content side="top" align="start">
<p>Positioned at top-start</p>
</Popover.Content>
</Popover.Root>
);
}

Popover with Arrow​

Popover with a decorative arrow pointing to the trigger:

export function PopoverWithArrow() {
return (
<Popover.Root>
<Popover.Trigger>Show Popover</Popover.Trigger>
<Popover.Content>
<Popover.Arrow />
<p>Content with arrow</p>
</Popover.Content>
</Popover.Root>
);
}

With Focus Management Callbacks​

Popover with custom focus management logic:

export function PopoverWithFocusCallbacks() {
const handleOpenAutoFocus = (event: Event) => {
console.log('Popover opening, focus is about to move inside');
// Prevent moving focus into the content:
// event.preventDefault();
};

const handleCloseAutoFocus = (event: Event) => {
console.log('Popover closed, focus returned to trigger');
// Prevent returning focus to trigger:
// event.preventDefault();
};

return (
<Popover.Root>
<Popover.Trigger>Open Popover</Popover.Trigger>
<Popover.Content
onOpenAutoFocus={handleOpenAutoFocus}
onCloseAutoFocus={handleCloseAutoFocus}
>
<input placeholder="Auto-focused input" />
<Popover.Close>Close</Popover.Close>
</Popover.Content>
</Popover.Root>
);
}

With Outside Interaction Handling​

Popover with custom outside interaction logic:

export function PopoverWithOutsideHandlers() {
const handlePointerDownOutside = (event: PointerEvent) => {
console.log('Clicked outside popover');
// Prevent close on outside pointer interaction:
// event.preventDefault();
};

const handleEscapeKeyDown = (event: KeyboardEvent) => {
console.log('Escape key pressed');
// Prevent close on Escape:
// event.preventDefault();
};

return (
<Popover.Root>
<Popover.Trigger>Open Popover</Popover.Trigger>
<Popover.Content
onPointerDownOutside={handlePointerDownOutside}
onEscapeKeyDown={handleEscapeKeyDown}
>
<p>Try clicking outside or pressing Escape</p>
</Popover.Content>
</Popover.Root>
);
}

Custom Portal Container​

Popover rendered in a specific container element:

export function PopoverWithCustomPortal() {
const [container, setContainer] = React.useState<HTMLElement | null>(null);

return (
<div>
<div ref={setContainer} id="custom-portal" />

<Popover.Root>
<Popover.Trigger>Open Popover</Popover.Trigger>
<Popover.Content container={container}>
<p>Rendered in custom container</p>
</Popover.Content>
</Popover.Root>
</div>
);
}

API Reference​

Popover / Popover.Root​

The root container that provides context and manages state for all popover components within it. Popover and Popover.Root are the same component - the difference is only import/notation style.

Props

NameTypeDefaultDescription
id?stringundefinedCustom base ID for ARIA relationships (${id}-trigger, ${id}-content)
open?booleanundefinedControlled open state
onOpenChange?(open: boolean) => voidundefinedCalled when open state changes
defaultOpen?booleanfalseInitial open state in uncontrolled mode
modal?booleanfalseEnables modal behavior for content
disabled?booleanfalseDisables trigger-driven opening/toggling
children?React.ReactNodeundefinedCompound parts (Popover.Trigger, Popover.Content, optional children)

Events

NameParametersDescriptionWhen Triggered
onOpenChange(open: boolean)State changes when opened/closedUser interaction or programmatic change

HTML Attributes

AttributeValuePurpose
data-state"open" | "closed"Indicates popover state

Popover.Trigger​

Button element that toggles the popover visibility. Extends all Button component props including polymorphic rendering via the as prop.

Props

NameTypeDefaultDescription
as?React.ElementType"button"Polymorphic element type
children?React.ReactNode | ((state: PopoverTriggerRenderProps) => React.ReactNode)undefinedTrigger content or render function
disabled?booleanfalseDisables trigger interaction (also respects Popover.Root disabled)
isLoading?booleanfalseInherited from Button; blocks interactive activation
isPressed?booleanundefinedInherited toggle state from Button
onPressedChange?(pressed: boolean) => voidundefinedInherited toggle callback from Button
...propsPopoverTriggerProps<T>undefinedInherits polymorphic button props (including native HTML and event handlers)

Render Props (PopoverTriggerRenderProps)

PropertyTypeDescription
isOpenbooleanWhether the popover is currently visible
disabledbooleanWhether the trigger is disabled
open() => voidFunction to programmatically open the popover
close() => voidFunction to programmatically close the popover
toggle() => voidFunction to programmatically toggle the popover

Events

NameParametersDescriptionWhen Triggered
onClick(event: React.MouseEvent<HTMLButtonElement>)Trigger clickedMouse click on trigger
onKeyDown(event: React.KeyboardEvent<HTMLButtonElement>)Key pressed on triggerKeyboard interaction

HTML Attributes

AttributeValuePurpose
idstring${id}-trigger from root context (overridable via the id prop)
aria-expandedbooleanReflects open state
aria-controlsstringPoints to content ID from root context
aria-haspopup"dialog"Announces popup type
data-state"open" | "closed"Styling/state hook
data-disabled""Present when disabled (inherited from Button)
disabledbooleanNative disabled attribute when rendered as a native <button>
aria-disabledtrueApplied when disabled and rendered as non-button element (inherited from Button)

Popover.Content​

Floating panel container that holds the popover content.

Props

NameTypeDefaultDescription
as?React.ElementType"div"Polymorphic element type
side?"top" | "bottom" | "left" | "right""bottom"Preferred side
align?"start" | "center" | "end""center"Preferred alignment
container?HTMLElement | nulldocument.bodyPortal container
onOpenAutoFocus?(event: Event) => voidundefinedCalled before open-time focus move into content; event.preventDefault() skips it
onCloseAutoFocus?(event: Event) => voidundefinedCalled during close; event.preventDefault() prevents restoring focus to trigger
onEscapeKeyDown?(event: KeyboardEvent) => voidundefinedCalled on Escape; event.preventDefault() prevents close
onPointerDownOutside?(event: PointerEvent) => voidundefinedCalled on pointer-down outside; event.preventDefault() prevents close
onFocusOutside?(event: FocusEvent) => voidundefinedCalled on focus moving outside (cancelable event); event.preventDefault() prevents close
onInteractOutside?(event: PointerEvent | FocusEvent) => voidundefinedCalled for both outside pointer and outside focus; event.preventDefault() prevents close
trapFocus?booleanfalseEnables focus trap while open (modal also enables focus trap)
children?React.ReactNodeundefinedPopover panel content
...propsPopoverContentProps<T>undefinedInherits polymorphic element props (including style, onKeyDown, HTML attributes)

Events

NameParametersDescriptionWhen Triggered
onOpenAutoFocus(event: Event)Open-time focus hook (cancelable)Content opens, before auto-focus
onCloseAutoFocus(event: Event)Close-time focus restore hookContent closes
onEscapeKeyDown(event: KeyboardEvent)Escape key hookEscape is pressed while open
onPointerDownOutside(event: PointerEvent)Pointer outside hookPointer down occurs outside content
onFocusOutside(event: FocusEvent)Focus outside hookFocus moves outside content
onInteractOutside(event: PointerEvent | FocusEvent)Combined outside interaction hookOutside pointer/focus interactions
onKeyDown(event: React.KeyboardEvent<HTMLDivElement>)Element keydown handler from HTML propsKeydown on the content element

HTML Attributes

AttributeValuePurpose
idstring${id}-content from root
tabIndex-1Allows programmatic focus
data-state"open"Always open when rendered
data-side"top" | "bottom" | "left" | "right"Actual positioned side
data-align"start" | "center" | "end"Actual alignment
role"dialog"Applied when modal={true}
aria-modal"true"Applied when modal={true}

Popover.Arrow​

Optional decorative arrow element that points to the trigger. Headless: renders a plain element with no visual opinions — user provides all styling.

Supports polymorphic rendering via the as prop. When rendered as the default svg, sensible SVG defaults (width, height, viewBox, and a triangle polygon) are applied automatically. When rendered as another element (e.g., as="div"), SVG-specific attributes and default children are omitted.

Props

NameTypeDefaultDescription
as?React.ElementType"svg"Polymorphic element type
children?React.ReactNodeundefinedCustom arrow content; when omitted and as="svg", a default triangle is rendered
...propsPopoverArrowProps<T>undefinedInherits polymorphic element props (including style, className, SVG attributes)

Events

NameParametersDescriptionWhen Triggered
None-Arrow is purely decorative-

HTML Attributes

AttributeValuePurpose
aria-hidden"true"Hidden from assistive technology
data-placement"top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end"Computed from content side + align
width10Default SVG width (as="svg")
height5Default SVG height (as="svg")
viewBox"0 0 10 5"Default SVG viewBox (as="svg")

Popover.Close​

Close button component that automatically closes the popover when clicked. Extends all Button component props including polymorphic rendering via the as prop.

Props

NameTypeDefaultDescription
as?React.ElementType"button"Polymorphic element type
children?React.ReactNode | ((state: PopoverCloseRenderProps) => React.ReactNode)undefinedClose content or render function
disabled?booleanfalseInherited from Button
isLoading?booleanfalseInherited from Button; blocks interactive activation
isPressed?booleanundefinedInherited toggle state from Button
onPressedChange?(pressed: boolean) => voidundefinedInherited toggle callback from Button
...propsPopoverCloseProps<T>undefinedInherits polymorphic button props (including native HTML and event handlers)

Render Props (PopoverCloseRenderProps)

PropertyTypeDescription
isOpenbooleanWhether the popover is currently visible
close() => voidFunction to close the popover

Events

NameParametersDescriptionWhen Triggered
onClick(event: React.MouseEvent<HTMLButtonElement>)Close button clickedMouse click on close button

HTML Attributes

AttributeValuePurpose
data-popover-close""Identifies close trigger
data-disabled""Present when disabled (inherited from Button)
type"button"Native button type when rendered as a native <button>
disabledbooleanNative disabled attribute when rendered as a native <button>
aria-disabledtrueApplied when disabled and rendered as non-button element

Keyboard Interactions​

Complete keyboard behavior for the popover component:

KeyActionContextNotes
EnterToggle popoverFocused Popover.TriggerTrigger inherits Button keyboard activation
SpaceToggle popoverFocused Popover.TriggerSame activation path as Enter
ArrowDownOpen popoverFocused Popover.TriggerOpens only if currently closed (does not toggle closed)
EscapeClose popoverWhile popover is openCan be prevented with onEscapeKeyDown(event.preventDefault())
HomeFocus first itemFocus is inside Popover.ContentMoves focus to first focusable element in content
EndFocus last itemFocus is inside Popover.ContentMoves focus to last focusable element in content
TabWrap to first elementFocus trap active (modal or trapFocus)Wrap occurs only when focus is on the last focusable element
Shift + TabWrap to last elementFocus trap active (modal or trapFocus)Wrap occurs only when focus is on the first focusable element