React Popover Component

A lightweight, fully-featured, accessible, and customizable popover component for React apps.

Features

• 🎯 12 placement options with smart auto-positioning
• 🎨 Smooth animations and transitions
• 🔄 Multiple trigger types (click, hover, focus)
• 📱 Responsive and mobile-friendly
• ♿ Accessible (WAI-ARIA compliant)
• 🎛️ Controlled and uncontrolled modes
• 🎯 Auto-placement to stay within viewport
• 🖌️ Highly customizable styling
• 📦 TypeScript support
• ⚡ Optimized performance
• ❌ No external dependencies

API documentation website

Installation

npm install @atawi/react-popover

Basic Usage

import { Popover } from "@atawi/react-popover";
import "@atawi/react-popover/dist/style.css"; // Optional: Import default styles

function App() {
  return (
    <Popover
      trigger={<button>Click me</button>}
      content={<div>Popover content</div>}
      placement="top"
    />
  );
}

Props

Prop	Type	Default	Description
trigger	ReactNode	-	The element that triggers the popover
content	ReactNode	-	The content to display in the popover
placement	PopoverPlacement	'top'	Preferred placement of the popover
offset	number	8	Distance between trigger and popover
className	string	''	Class name for the popover wrapper
containerClassName	string	''	Class name for the container
contentClassName	string	''	Class name for the content wrapper
animatedClassName	string	''	Custom class name for animated state
enterClassName	string	''	Custom class name for enter animation
exitClassName	string	''	Custom class name for exit animation
open	boolean	-	Control popover visibility externally
onOpenChange	(open: boolean) => void	-	Callback when visibility changes
style	CSSProperties	-	Additional styles for the popover
autoPlacement	boolean	false	Enable automatic repositioning
animated	boolean	false	Enable enter/exit animations
triggerType	PopoverTrigger | PopoverTrigger[]	'click'	How to trigger the popover
hoverDelay	number	200	Delay before showing on hover
closeDelay	number	400	Delay before hiding on hover out
closeOnScroll	boolean	false	Close popover when window is scrolled
closeOnResize	boolean	false	Close popover when window is resized

Examples

Basic Popover

<Popover
  trigger={<button>Click me</button>}
  content="Simple popover content"
  placement="top"
/>

With Auto-placement

<Popover
  trigger={<button>Hover me</button>}
  content="Content that stays in viewport"
  placement="top"
  autoPlacement
  triggerType="hover"
/>

Animated Popover

<Popover
  trigger={<button>Animated</button>}
  content="Smooth animation"
  placement="right"
  animated
/>

Multiple Triggers

<Popover
  trigger={<button>Interactive</button>}
  content="Accessible content"
  placement="bottom"
  triggerType={["hover", "focus"]}
/>

Controlled Mode

function ControlledExample() {
  const [open, setOpen] = useState(false);

  return (
    <Popover
      trigger={<button>Controlled</button>}
      content="Controlled content"
      open={open}
      onOpenChange={setOpen}
    />
  );
}

Custom Styling

<Popover
  trigger={<button>Styled</button>}
  content="Custom styled content"
  className="custom-popover"
  contentClassName="custom-content"
  style={{ maxWidth: "300px" }}
/>

Custom Animations

<Popover
  trigger={<button>Custom Animation</button>}
  content="Smoothly animated content"
  animated
  animatedClassName="my-popover-animated"
  enterClassName="my-popover-enter"
  exitClassName="my-popover-exit"
/>

.my-popover-animated {
  transition: all 300ms cubic-bezier(0.4, 0, 0.2, 1);
}

.my-popover-enter {
  opacity: 1;
  transform: scale(1) translateY(0);
}

.my-popover-exit {
  opacity: 0;
  transform: scale(0.9) translateY(-8px);
}

Placement Options

The placement prop accepts the following values:

• top | top-start | top-end
• bottom | bottom-start | bottom-end
• left | left-start | left-end
• right | right-start | right-end

Trigger Types

The triggerType prop accepts:

• 'click' - Opens on click/tap
• 'hover' - Opens on mouse hover
• 'focus' - Opens on focus (keyboard navigation)
• Array of the above for multiple triggers

Styling

The component uses CSS modules and provides several class names for customization:

• .container - The root container
• .trigger - The trigger wrapper
• .content - The popover content wrapper
• .contentInner - The inner content container
• .animated - Applied when animations are enabled
• .enter - Applied during enter animation
• .exit - Applied during exit animation

Custom Animation Classes

For complete control over animations, use the animation className props:

• animatedClassName - Replaces the default animated class
• enterClassName - Replaces the default enter class
• exitClassName - Replaces the default exit class

This allows you to bypass CSS modules hashing and use your own class names.

Accessibility

The component follows WAI-ARIA guidelines:

• Proper ARIA attributes
• Keyboard navigation support
• Focus management
• Screen reader friendly

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• IE11 (with polyfills)

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

License

MIT © Atawi