General

Popover

Copy page

View as Markdown

Open in ChatGPT

Open in Claude

Displays rich content in a portal, triggered by a button.

Usage#

app.component.ts

import { WdsPopoverComponent } from '@wds/angular/popover';

Put the button in the trigger slot and the content in the default slot. Name the panel with heading (or label when it has no title). For a short text on hover use Tooltip, for a list of actions Dropdown.

Examples#

Default#

A click on the trigger opens the panel below it; heading and description add a title and a description at the top. A click outside, Escape or moving focus out of the panel closes it.

Open popover

Width

Max. width

Height

Max. height

Show code

popover-default.ts

import { Component } from '@angular/core';
import { WdsPopoverComponent } from '@wds/angular/popover';
import { WdsButtonComponent } from '@wds/angular/button';
import { WdsFieldComponent, WdsFieldGroupComponent, WdsFieldLabelComponent } from '@wds/angular/field';
import { WdsInputComponent } from '@wds/angular/input';

@Component({
  selector: 'app-popover-default-demo',
  imports: [WdsPopoverComponent, WdsButtonComponent, WdsFieldGroupComponent, WdsFieldComponent, WdsFieldLabelComponent, WdsInputComponent],
  template: `
    <wds-popover heading="Dimensions" description="Set the dimensions for the layer.">
      <wds-button slot="trigger" variant="outline">Open popover</wds-button>
      <wds-field-group class="gap-3">
        <wds-field orientation="horizontal">
          <wds-field-label class="w-1/2">Width</wds-field-label>
          <wds-input value="100%"></wds-input>
        </wds-field>
        <wds-field orientation="horizontal">
          <wds-field-label class="w-1/2">Max. width</wds-field-label>
          <wds-input value="300px"></wds-input>
        </wds-field>
        <wds-field orientation="horizontal">
          <wds-field-label class="w-1/2">Height</wds-field-label>
          <wds-input value="25px"></wds-input>
        </wds-field>
        <wds-field orientation="horizontal">
          <wds-field-label class="w-1/2">Max. height</wds-field-label>
          <wds-input value="none"></wds-input>
        </wds-field>
      </wds-field-group>
    </wds-popover>
  `,
})
export class PopoverDefaultDemo {}

Side#

side places the panel bottom (default), top, left or right of the trigger. Without enough space it flips to the other side.

Left

The panel opens on the left.

Top

The panel opens on the top.

Bottom

The panel opens on the bottom.

Right

The panel opens on the right.

Show code

popover-side.ts

import { Component } from '@angular/core';
import { WdsPopoverComponent } from '@wds/angular/popover';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-popover-side-demo',
  imports: [WdsPopoverComponent, WdsButtonComponent],
  template: `
    <div class="flex flex-wrap gap-2">
      <wds-popover side="left" label="Left">
        <wds-button slot="trigger" variant="outline">Left</wds-button>
        <div>The panel opens on the left.</div>
      </wds-popover>
      <wds-popover side="top" label="Top">
        <wds-button slot="trigger" variant="outline">Top</wds-button>
        <div>The panel opens on the top.</div>
      </wds-popover>
      <wds-popover side="bottom" label="Bottom">
        <wds-button slot="trigger" variant="outline">Bottom</wds-button>
        <div>The panel opens on the bottom.</div>
      </wds-popover>
      <wds-popover side="right" label="Right">
        <wds-button slot="trigger" variant="outline">Right</wds-button>
        <div>The panel opens on the right.</div>
      </wds-popover>
    </div>
  `,
})
export class PopoverSideDemo {}

Align#

align aligns the panel with the start, center (default) or end of the trigger (in right-to-left text start is the right edge). --wds-popover-width sets the width of the panel (default 18rem).

Show code

popover-align.ts

import { Component } from '@angular/core';
import { WdsPopoverComponent } from '@wds/angular/popover';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-popover-align-demo',
  imports: [WdsPopoverComponent, WdsButtonComponent],
  template: `
    <div class="flex flex-wrap gap-2">
      <wds-popover align="start" label="Start" class="[--wds-popover-width:10rem]">
        <wds-button slot="trigger" variant="outline">Start</wds-button>
        <div>Aligned to the start.</div>
      </wds-popover>
      <wds-popover align="center" label="Center" class="[--wds-popover-width:10rem]">
        <wds-button slot="trigger" variant="outline">Center</wds-button>
        <div>Aligned to the center.</div>
      </wds-popover>
      <wds-popover align="end" label="End" class="[--wds-popover-width:10rem]">
        <wds-button slot="trigger" variant="outline">End</wds-button>
        <div>Aligned to the end.</div>
      </wds-popover>
    </div>
  `,
})
export class PopoverAlignDemo {}

User profile#

Details of a person with actions. Without a visible title, label names the panel.

MS Mira Stone

Mira Stone [email protected]

Admin

Product designer in the Growth team. Based in Lisbon, works 9:00–17:00 WET.

Message

View profile

Show code

popover-profile.ts

import { Component } from '@angular/core';
import { WdsPopoverComponent } from '@wds/angular/popover';
import { WdsButtonComponent } from '@wds/angular/button';
import { WdsAvatarComponent } from '@wds/angular/avatar';
import { WdsBadgeComponent } from '@wds/angular/badge';

@Component({
  selector: 'app-popover-profile-demo',
  imports: [WdsPopoverComponent, WdsButtonComponent, WdsAvatarComponent, WdsBadgeComponent],
  template: `
    <wds-popover align="start" label="Mira Stone">
      <wds-button slot="trigger" variant="ghost" class="gap-2">
        <wds-avatar size="sm" src="https://github.com/octocat.png">MS</wds-avatar>
        Mira Stone
      </wds-button>
      <div class="flex items-start gap-3">
        <wds-avatar size="lg" src="https://github.com/octocat.png">MS</wds-avatar>
        <div class="grid min-w-0 gap-0.5">
          <span class="font-medium">Mira Stone</span>
          <span class="truncate text-muted-foreground">mira&#64;example.com</span>
          <wds-badge variant="secondary" class="mt-1 w-fit">Admin</wds-badge>
        </div>
      </div>
      <div class="text-muted-foreground">Product designer in the Growth team. Based in Lisbon, works 9:00–17:00 WET.</div>
      <div class="grid grid-cols-2 gap-2">
        <wds-button variant="outline" size="sm">Message</wds-button>
        <wds-button size="sm" href="#">View profile</wds-button>
      </div>
    </wds-popover>
  `,
})
export class PopoverProfileDemo {}

Settings#

Quick settings behind an icon button. The changes apply at once, so the panel needs no Save button.

Comments

Mentions

Weekly summary

Show code

popover-settings.ts

import { Component } from '@angular/core';
import { WdsPopoverComponent } from '@wds/angular/popover';
import { WdsButtonComponent } from '@wds/angular/button';
import { WdsSwitchComponent } from '@wds/angular/switch';

@Component({
  selector: 'app-popover-settings-demo',
  imports: [WdsPopoverComponent, WdsButtonComponent, WdsSwitchComponent],
  template: `
    <wds-popover heading="Notifications" description="Choose what you hear about." align="end">
      <wds-button slot="trigger" variant="outline" size="icon" label="Notification settings">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.268 21a2 2 0 0 0 3.464 0" /><path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326" /></svg>
      </wds-button>
      <div class="grid gap-3">
        <wds-switch checked>Comments</wds-switch>
        <wds-switch checked>Mentions</wds-switch>
        <wds-switch>Weekly summary</wds-switch>
      </div>
    </wds-popover>
  `,
})
export class PopoverSettingsDemo {}

An element with autofocus gets focus when the panel opens, here the field with the link. Without it, focus goes to the panel, and Tab moves to its first control.

Copy

Show code

popover-share.ts

import { Component } from '@angular/core';
import { WdsPopoverComponent } from '@wds/angular/popover';
import { WdsButtonComponent } from '@wds/angular/button';
import { WdsInputComponent } from '@wds/angular/input';

@Component({
  selector: 'app-popover-share-demo',
  imports: [WdsPopoverComponent, WdsButtonComponent, WdsInputComponent],
  template: `
    <wds-popover heading="Share link" description="Anyone with the link can view this document." align="start">
      <wds-button slot="trigger">Share</wds-button>
      <div class="flex gap-2">
        <wds-input class="flex-1" aria-label="Link" value="https://example.com/d/q4-report" readonly autofocus></wds-input>
        <wds-button variant="outline">Copy</wds-button>
      </div>
    </wds-popover>
  `,
})
export class PopoverShareDemo {}

API References#

Rich content in a floating panel, opened by a button: a short form, details, settings. The panel opens in the top layer (Popover API) next to the trigger and is a non-modal dialog: the rest of the page stays usable. A click outside, Escape or moving focus out of the panel closes it.

Attributes

Attribute	Type	Default	Description
open	boolean	false	Whether the panel is open. Also set by `show()`, `close()` and `toggle()`.
side	WdsPopoverSide	'bottom'	Side of the trigger. Flips when there is not enough space.
align	WdsPopoverAlign	'center'	Alignment along the trigger.
offset	number	4	Distance from the trigger in px.
heading	string	''	Title at the top of the panel; it names the dialog.
description	string	''	Description under the title, linked as `aria-describedby`.
label	string \| undefined		Accessible name of the panel when it has no `heading`.
disabled	boolean	false	Disables opening the panel.

Events

Event	Description
wds-open-changeCustomEvent<WdsPopoverOpenChangeDetail>	The panel opens or closes.

Methods

Method	Description
show()	Opens the panel.
close()	Closes the panel. Focus goes back to the trigger when it was inside the panel.
toggle()	Opens or closes the panel.

Slots

Slot	Description
trigger	The button that opens the panel (e.g. `wds-button`). It gets `aria-haspopup="dialog"` and `aria-expanded`.
(default)	Panel content. An element with `autofocus` gets focus when the panel opens; otherwise the panel itself.

CSS parts (::part)

Part	Description
content	The panel.
header	Title and description.
title	The title.
description	The description.

CSS custom properties

Property	Description
--wds-popover-width	Width of the panel (default 18rem).

Accessibility#

The panel is a non-modal dialog (role="dialog") named by heading or label; description is linked with aria-describedby.

The trigger gets aria-haspopup="dialog" and aria-expanded; wds-button forwards them to its native button.

When the panel opens, focus moves into it, so screen readers announce its name. Escape returns focus to the trigger.

The panel is not modal: the rest of the page stays available, and moving focus out of the panel closes it.

Keyboard support#

Key	Function
Enter	On the trigger: opens or closes the panel.
Space	On the trigger: opens or closes the panel.
Tab	Moves focus to the next control in the panel. Moving focus out of the panel closes it.
ShiftTab	Moves focus to the previous control.
Escape	Closes the panel and returns focus to the trigger.

Usage#

Examples#

Default#

Side#

Align#

User profile#

Settings#

Autofocus#

API References#

wds-popover#

Attributes

Events

Methods

Slots

CSS parts (::part)

CSS custom properties

Accessibility#

Screen reader#

Keyboard support#