Aliases
anchored surface
components / popover
Popover
Anchored floating surface with deterministic placement and dismissal for contextual supporting content.
Playground
Live playground
Start here. Switch systems, interact with the shipped component, and let the rest of the page answer the why and how after the behavior clicks.
Cobalt
bottom popover
The crisp default DK action system: bright primary, roomy spacing, and a direct editorial rhythm.
Overview
What it is
This section explains the intent of the component before the implementation details.
- Popover is the anchored surface for contextual supporting content that is richer than a tooltip but lighter than a dialog.
- It keeps the trigger relationship visually obvious while still providing a contained surface.
Explore the math
Decision guide
How to choose it
Use these notes to decide quickly whether this is the right DK component for the job.
Decision guide
- Choose Popover when the interaction should feel deliberate, documented, and reusable across product surfaces.
- If the scenario is more specialized than the current Popover contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.
Do
- Keep the Popover label, value, or status language direct enough to scan quickly.
- Use the documented size and state recipes instead of inventing one-off variants in product code.
Do not
- Do not hide the main purpose of Popover behind decorative copy or overloaded surface treatments.
- Do not stretch Popover into a workflow it was not designed to handle just because the visuals are close.
Usage
When to use
Prefer these situations when choosing this component.
- Use Popover for contextual content or controls that belong near the triggering element.
- Use it when the content should not take over the page.
Usage
When not to use
These patterns are better served by a different component or a simpler surface.
- Do not use Popover for critical modal tasks.
- Do not use Popover for single-sentence hints; use Tooltip.
Anti-patterns
- Using Popover as a generic layout container instead of a purpose-built interaction or content surface.
- Forking the documented recipe in product code instead of extending the shared DK contract.
Migration notes
- Migrate legacy popover usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
- Treat the docs examples as the reference contract for accessibility and event behavior during adoption.
Anatomy
Structural parts
The anatomy explains which pieces matter to the recipe and accessibility model.
open affordance
triggerControl that opens the popover.
anchored container
surfaceFloating contextual surface.
API
Public interface
The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.
Props
| Name | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Controlled open state. |
placement | 'top' | 'right' | 'bottom' | 'left' | 'bottom' | Preferred anchor placement. |
size | 'sm' | 'md' | 'md' | Chooses the popover size recipe. |
closeOnEscape | boolean | true | Allows Escape dismissal. |
closeOnOutsidePress | boolean | true | Allows outside press dismissal. |
onOpenChange | (detail: { open: boolean }) => void | — | Callback fired when the popover opens or closes. |
theme | ThemeContract | — | Overrides the compiled DK theme used to resolve tokens and recipes for this component. |
Events
| Name | Payload | Description |
|---|---|---|
openchange | { open: boolean } | Fires when an overlay-style component opens or closes through user interaction. |
Slots
| Name | Description |
|---|---|
trigger | Trigger content. |
default | Popover body content. |
Recipes
Variants, sizes, and states
These notes summarize the intended recipe surface rather than exposing raw implementation detail first.
Variants
- top/right/bottom/left: Placement chooses the preferred anchored direction with collision handling.
Sizes
- sm: Compact popover
- md: Default popover
States
- closed: Popover hidden
- open: Popover visible
Accessibility
Accessibility contract
This is the behavior the component promises to assistive tech and keyboard users today.
Semantics
- Uses overlay semantics that reflect whether the surface is modal, contextual, or advisory.
- Uses a contextual overlay surface that remains associated with the trigger.
Keyboard
- Supports Escape dismissal when allowed.
- Returns focus to the trigger after closing.
Screen readers
- Announces the overlay surface with its title, description, or tooltip content as available.
Checklist
- Verify the visible label or title still produces a clear accessible name.
- Verify focus remains obvious in every supported state and size.
- Verify disabled, selected, and error states do not rely on color alone.
Implementation
Tokens and slot vars
This section shows the representative compiled slot variables that the runtime consumes for the selected design system.
root
- --dk-motion-duration
- 200ms
- --dk-popover-offset
- 12px
surface
- --dk-popover-surface-bg
- #f2f5fb
- --dk-popover-surface-fg
- #16181c
- --dk-popover-surface-border
- #95989d
- --dk-popover-surface-radius
- clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
- --dk-popover-surface-shadow
- 0 10px 15px rgba(0, 0, 0, 0.06), 0 4px 6px rgba(0, 0, 0, 0.04)
- --dk-popover-surface-width
- 260px
- --dk-popover-surface-padding
- clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
content
- --dk-popover-content-size
- clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
Implementation notes
- Popover is contextual, not blocking. Keep the content focused and avoid turning it into an accidental modal.
Implementation checklist
- Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
- Keep theme overrides token-driven so proofs and recipes stay meaningful.
- Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.
Examples
Copy-paste examples
Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.
Starter
1 example
starter
Starter: contextual surfaceA simple anchored contextual surface.
Copy snippet
<Popover placement="bottom"><svelte:fragment slot="trigger">Open popover</svelte:fragment>Popover body</Popover>Common patterns
1 example
common
Common: side placementSide placement works well for toolbar or inline action clusters.
Copy snippet
<Popover placement="right"><svelte:fragment slot="trigger">Details</svelte:fragment>Supporting context</Popover>Edge cases
1 example
edge
Edge: controlled contextual stateControl popover state when the surrounding app owns its visibility.
Copy snippet
<Popover open={isOpen} onOpenChange={(detail) => isOpen = detail.open}><svelte:fragment slot="trigger">Open popover</svelte:fragment>Popover body</Popover>Verification
Curated proof fixtures
Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.
default (size=sm)
passsize=sm
- Contrast: 98.5 Lc
- Surface: 220x220
default (size=md)
passsize=md
- Contrast: 98.5 Lc
- Surface: 260x220
large
passsize=lg
- Contrast: 98.5 Lc
- Surface: 320x220