# @synerise/ds-popover

> Popover UI Component for the Synerise Design System

Latest version **2.0.3** (published 2026-09-22) · ISC license · 0 weekly downloads

## Install

```sh
npm install @synerise/ds-popover
pnpm add @synerise/ds-popover
yarn add @synerise/ds-popover
bun add @synerise/ds-popover
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2026-09-22 |
| First published | 2025-11-06 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 51.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | synerise |

## Links

- npm: https://www.npmjs.com/package/@synerise/ds-popover
- Repository: Synerise/synerise-design
- npm.io page: https://npm.io/package/@synerise/ds-popover

## Dependencies (2)

- [classnames](https://npm.io/package/classnames.md) ^2.5.1
- [@floating-ui/react](https://npm.io/package/@floating-ui/react.md) ^0.27.16

## Recent versions

- 2.0.3 (latest) — 2026-09-22
- 2.0.2 — 2026-09-18
- 2.0.1 — 2026-09-08
- 2.0.0 — 2026-08-26
- 1.7.0 — 2026-08-18
- 1.6.3 — 2026-08-11
- 1.6.2 — 2026-07-23
- 1.6.1 — 2026-05-26
- 1.6.0 — 2026-05-22
- 1.5.5 — 2026-05-04
- 1.5.4 — 2026-04-10
- 1.5.3 — 2026-03-24
- 1.5.2 — 2026-03-23
- 1.5.1 — 2026-02-23
- 1.5.0 — 2026-02-19
- … 8 more at https://npm.io/package/@synerise/ds-popover/versions

## README

---
id: popover
title: Popover
---

Popover UI Component

## Installation
```
npm i @synerise/ds-popover
or
pnpm add @synerise/ds-popover
or
yarn add @synerise/ds-popover
```

## Usage
```jsx
import Popover, { PopoverTrigger, PopoverContent } from '@synerise/ds-popover'

<Popover>
  <PopoverTrigger><button>Open</button></PopoverTrigger>
  <PopoverContent>Content</PopoverContent>
</Popover>
```

## Demo

<iframe src="/storybook-static/iframe.html?id=components-popover--default"></iframe>

## API

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| placement | Floating-ui placement | `Placement` | `'bottom'` |
| trigger | Interaction type to open popover | `'click' \| 'hover' \| ('click' \| 'hover')[]` | `'click'` |
| open | Controlled open state | `boolean` | - |
| onOpenChange | Controlled open/close handler | `(open: boolean, event?: Event, reason?: OpenChangeReason) => void` | - |
| onDismiss | Called on escape-key or outside-press dismiss | `(event?: Event, reason?: OpenChangeReason) => void` | - |
| modal | Trap focus inside popover | `boolean` | `false` |
| initialOpen | Uncontrolled initial open state | `boolean` | `false` |
| returnFocus | Return focus to trigger on close | `boolean` | `true` |
| closeOnFocusOut | Close the popover when focus leaves it (e.g. tabbing out); Escape and outside-press still dismiss | `boolean` | `true` |
| testId | Sets data-testid on trigger and content | `string` | `'noTestId'` |
| componentId | Sets data-popover-{id} attribute on content | `string` | - |
| zIndex | CSS z-index of floating panel | `number` | `theme.variables['zindex-dropdown']` |
| autoUpdate | Reposition while both elements are mounted | `boolean \| AutoUpdateOptions` | - |
| offsetConfig | floating-ui offset middleware options (add `enabled: false` to disable) | `OffsetConfig` | `{ enabled: true }` |
| flipConfig | floating-ui flip middleware options | `FlipConfig` | `{ enabled: true }` |
| shiftConfig | floating-ui shift middleware options | `ShiftConfig` | `{ enabled: true }` |
| arrowConfig | floating-ui arrow middleware options (element managed by PopoverArrow) | `Omit<ArrowOptions, 'element'>` | `{}` |
| hoverConfig | Extra options for useHover (e.g. restMs, move) | `HoverConfig` | `{}` |
| dismissConfig | Extra options for useDismiss | `UseDismissProps` | `{}` |
| listNavigationConfig | Keyboard list navigation config | `UseListNavigationProps` | `{ enabled: false }` |
| transitionDuration | Transition duration in ms (enables CSS transitions) | `number` | - |
| getTransitionConfig | Custom transition styles factory | `({ placement }) => Partial<UseTransitionStylesProps>` | opacity fade |
| getPopupContainer | Custom portal root container | `(element: HTMLElement) => HTMLElement` | - |
| overlayKind | Kind reported to the overlay registry, so `closeAllOverlays({ kinds })` can target it | `OverlayKind` | `'popover'` |

## Closing programmatically

`closeAllOverlays()` from `@synerise/ds-core` force-closes every open DS overlay in one call — useful when an app-level event (e.g. the active workspace changed in another tab) invalidates whatever the user is doing. This component closes through its own close path, so its handlers fire and focus is restored.

```ts
import { closeAllOverlays } from '@synerise/ds-core';

await closeAllOverlays();
await closeAllOverlays({ kinds: ['modal', 'drawer'] }); // leave tooltips alone
```

---
_Source: https://npm.io/package/@synerise/ds-popover · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._