> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Popover

> Popovers, which are commonly triggered by Buttons, appear contextually near the trigger element allowing users to interact more efficiently with the UI. They are often used for lightweight interactions or providing contextual information in forms.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-popover--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--basic" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--basic&viewMode=story&globals=theme:light" title="Popover basic story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* For lightweight, contextual content or actions: Use Popovers to show information or actions directly related to a specific trigger (Button, icon, text).
* When you want to keep users in context: Popovers are non-blocking and allow users to stay on the same screen without major interruptions.
* To display additional details or previews on demand: For example, previewing user profile details on hover or click.
* When you need more space than a tooltip, but less than a Dialog: Popovers can hold controls like Buttons, which can provide additional links to more information or confirmative actions like a soft (non-destructive) delete.

## When to use something else

* Brief, passive hints on hover/focus with no controls inside: use [Tooltip](/cdf/aura/primitives/tooltip).
* Full attention, blocking flow, or critical decisions: use [Dialog](/cdf/aura/primitives/dialog) / [Alert dialog](/cdf/aura/primitives/alert-dialog) or a dedicated page.
* Choosing from a list of commands or values: use [Menu](/cdf/aura/primitives/dropdown-menu) or [Select](/cdf/aura/primitives/select), not a generic [Popover](/cdf/aura/primitives/popover).

## Dos and don'ts

* **Do** anchor the Popover clearly to a trigger element.
* **Do** use a Popover for secondary or optional tasks as they should enhance the primary workflow, not interrupt it.
* **Do** be mindful of screen boundaries and reposition the Popover if necessary as it should be fully visible when triggered without the user having to scroll to see it.
* **Don't** block essential content behind the Popover, or make sure the user can move the Popover to see the content.
* **Don't** allow more than one Popover to be displayed at a time.

## Behavior

* Non-modal overlay anchored to a trigger; dismisses on outside click and Escape unless the design requires persistent multi-control content.
* Repositions to remain in the viewport; may allow drag in implementations that support it—don't obscure essential content without a way to reveal it.

## Often used with

[Button](/cdf/aura/primitives/button) or subtle text trigger; compact forms ([Input](/cdf/aura/primitives/input), small [Button](/cdf/aura/primitives/button)); not a substitute for [Menu](/cdf/aura/primitives/dropdown-menu) command lists.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### Sides

Position the popover on different sides of the trigger depending on available viewport space and what content must remain visible.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--sides" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--sides&viewMode=story&globals=theme:light" title="Popover sides story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Alignment

Fine-tune alignment so the popover edge lines up with the trigger—useful when the trigger is narrow or sits near layout boundaries.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--alignment" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--alignment&viewMode=story&globals=theme:light" title="Popover alignment story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With form

Embed a compact form inside a popover for quick edits or secondary inputs without navigating away from the current view.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--with-form" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--with-form&viewMode=story&globals=theme:light" title="Popover with form story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Custom width

Set a custom width when default sizing is too narrow for form fields or too wide for short explanatory content.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--custom-width" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--custom-width&viewMode=story&globals=theme:light" title="Popover custom width story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Rich content

Use rich content—headings, lists, or actions—when the popover needs more structure than a single line of text or one button.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--rich-content" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--rich-content&viewMode=story&globals=theme:light" title="Popover rich content story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Controlled

Use a controlled popover when open state must sync with application logic, such as guided tours, URL parameters, or parent form state.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--controlled" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--controlled&viewMode=story&globals=theme:light" title="Popover controlled story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Empty content

Avoid shipping empty popovers in production; use this pattern only as a placeholder while content is being wired up.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--empty-content" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--empty-content&viewMode=story&globals=theme:light" title="Popover empty content story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Long content scrollable

Allow scrolling inside the popover when content exceeds the viewport so users can read everything without the panel growing off-screen.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--long-content-scrollable" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--long-content-scrollable&viewMode=story&globals=theme:light" title="Popover long content scrollable story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Narrow viewport

Test popover behavior on narrow viewports so repositioning and scrolling keep the panel fully visible and usable on small screens.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-popover--narrow-viewport" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-popover--narrow-viewport&viewMode=story&globals=theme:light" title="Popover narrow viewport story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>