On this page

Overlays

Popover released

A panel of content anchored to a control, with the page behind it still answering.

Import@pacit/components/popover
Selectorpct-popover

Implements the non-modal reading of the W3C ARIA APG Dialog pattern ↗

import { Component } from '@angular/core';
import { PctButton } from '@pacit/components/button';
import { PctPopover, PctPopoverTrigger } from '@pacit/components/popover';

/** A light panel anchored to its button — not modal, the page stays alive behind it. */
@Component({
  selector: 'demo-popover',
  imports: [PctButton, PctPopover, PctPopoverTrigger],
  template: `
    <button pctButton variant="outline" [pctPopoverTrigger]="filters">
      Filters
    </button>

    <pct-popover #filters heading="Filters">
      <p>Anything can live here — a form, a list, a calendar.</p>
    </pct-popover>
  `,
})
export class PopoverDemo {}

popover.demo.ts — the same file runs here and is highlighted under Code

Start here

Usage

One import per component, and the shortest possible use — the package itself is installed once, on the start page.

Import this component

import { PctPopover } from '@pacit/components/popover';

Exported	What it is
`PctPopover`component`pct-popover`	A popover: a panel of content hanging off the control that opened it, with focus inside it and the rest of the page still answering.
`PctPopoverTrigger`directive`[pctPopoverTrigger]`	The control a popover hangs off: it toggles the panel and says so about itself.
`PctPopoverCloseReason`type`'trigger' \| 'escape' \| 'outside' \| 'away' \| 'api'`	Why a popover closed. `open` says that it is shut and nothing else, and the question an application asks about a panel it did not close itself — did the user answer, or did they walk away from it — is answered by this and by nothing in the boolean.

<button pctButton [pctPopoverTrigger]="filters">Filters</button> <pct-popover #filters heading="Filters">…</pct-popover>

<!-- the same panel drawn where it stands: no layer, no anchor, and there from the server -->
<pct-popover inline [open]="true" heading="Filters">…</pct-popover>

<!-- one panel with two lives — a column on a wide page, a layer on a narrow one -->
<button pctButton [pctPopoverTrigger]="filters">Filters</button>
<pct-popover #filters [inline]="wide()" [(open)]="filtersOpen" heading="Filters">…</pct-popover>

Examples

Every state, running

Each example is the component itself, not a screenshot. Open the code under any of them.

Placement

Ask for a side with placement; the panel takes it when it fits and flips to the opposite side when the viewport says no — a wish, not an order.

API

What it reads, and what it writes back

Read from the source at build time — the types, the defaults and the lines of documentation are the library's own.

A popover: a panel of content hanging off the control that opened it, with focus inside it and the rest of the page still answering.

Inputs

Name	Type	What it does
`open`two-waydefault `false`	`boolean`	Whether the panel is up. A `model`, because both directions are ordinary: an application opens it, and the popover closes itself on Escape, on a press outside and on the trigger.
`heading`default `''`	`string`	The visible title, rendered as the panel's heading and used as its accessible name. A panel with no name is announced as "dialog" and nothing else, so an empty one is reported in dev mode rather than passed over.
`ariaLabel`default `''`	`string`	The accessible name of a popover with no visible heading — an INPUT and not an attribute on the tag, for the dialog's reason: the role sits on the panel inside the overlay, and the host carries none at all (`req-a11y-built-in`).
`ariaLabelledby`default `''`	`string`	As `ariaLabel`, for a name that already stands somewhere inside the content.
`placement`default `'bottom'`	`PctPlacement`	Which side of the trigger it opens on — logical, so `end` is the right in an English page and the left in an Arabic one. The window has the last word: a side with no room for the panel falls back to the one across the trigger (`pctPlacementPositions`). It says nothing `inline`: a panel drawn in the page is placed by the page.
`inline`default `false`	`boolean`	Draws the panel in the host, where the consumer wrote the component, instead of in an overlay over the page. The same template, the same classes, the same parts and the same stylesheet — a second panel written out for this case is the defect the input exists to avoid.

Outputs

Name	Payload	When it fires
`closed`	`PctPopoverCloseReason`	Why it closed. See `PctPopoverCloseReason`.

What it writes on the element

The hooks a stylesheet or a test can hold. Stable by contract — the parts inventory gate fails the build when one disappears.

Attribute	Bound to	Note
`class`	`pct-popover`
`style`	`display: contents`	The host draws nothing of its own in either mode: with an overlay everything it draws lives outside the tree, and it stays here because it is where the panel's severed properties are read from. `display: contents` is also what makes the inline panel land in the consumer's own layout — the host box is not there to be a wrapper between the page's grid and the panel it wrote into it.

Styling

Parts to select, tokens to override

Two ways in, both stable. No class names to depend on.

Parts

In a test, PctPopoverHarness, PctPopoverTriggerHarness from @pacit/components/testing read a part by the name below and a state by its attribute — the harness gate holds the names to the package.

Part	Selector	What it is
`content`	`[data-pct-part="content"]`	the projected body
`heading`	`[data-pct-part="heading"]`	the title the panel is named by
`panel`	`[data-pct-part="panel"]`	the floating box

Tokens

Every value the component reads, with the light and the dark default. Override a token at any scope and it cascades like any custom property.

Token	Styles
`--pct-popover-heading-fg{pct.text}`#0f172a · #ffffff	Text colour of the heading.
`--pct-popover-heading-font-size{pct.font.size.md}`14px	Font size of the heading.
`--pct-popover-heading-font-weight{pct.font.weight.medium}`500	Font weight of the heading.
`--pct-popover-panel-bg{pct.surface}`#ffffff · #0f172a	Background of the panel.
`--pct-popover-panel-border{pct.border-strong}`#64748b	Edge colour of the panel.
`--pct-popover-panel-fg{pct.text}`#0f172a · #ffffff	Text colour of the panel.
`--pct-popover-panel-gap{pct.space.3}`8px	Gap between the panel's heading and its content.
`--pct-popover-panel-max-width`320px	Maximum width of the panel.
`--pct-popover-panel-padding-x{pct.space.4}`12px	Horizontal padding of the panel.
`--pct-popover-panel-padding-y{pct.space.4}`12px	Vertical padding of the panel.
`--pct-popover-panel-radius{pct.radius.md}`8px	Corner radius of the panel.
`--pct-popover-panel-shadow{pct.shadow-panel}`0 8px 24px rgba(15, 23, 42, 0.14) · 0 8px 24px rgba(0, 0, 0, 0.55)	Shadow of the panel.

Theming

A brand override in a few declarations. Scope it to a theme attribute, a page or one container — the component never notices.

[data-theme='brand'] {
  --pct-popover-panel-bg: #f0fdfa;
  --pct-popover-panel-fg: #134e4a;
  --pct-popover-heading-fg: #0f766e;
}

Accessibility

Measured, not assumed

Pattern: the non-modal reading of Dialog — role="dialog" with no aria-modal, focus moved into the panel and given back to the trigger, Escape from the closing stack. The trigger is the Disclosure half: aria-expanded on the control, aria-haspopup="dialog", aria-controls while the panel is up

Keyboard

key	effect	test
`Escape`	closes it; focus goes back to the trigger if it was in the panel	`apps/sandbox-e2e/src/popover.spec.ts`
`Tab`	from the panel, into its content; from the last control, out — closing it and returning focus to the trigger	`apps/sandbox-e2e/src/popover.spec.ts`
`Shift+Tab`	from the first control, the same way out	`apps/sandbox-e2e/src/popover.spec.ts`
`Enter`/`Space` on the trigger	toggles it, which is the button's own behaviour and nothing this component adds	`libs/components/popover/src/popover.spec.ts`

The panel itself is not in the Tab order (tabindex="-1"); it is focused programmatically on opening, so that its role and name are announced before the user is anywhere inside it.

None of the first three rows is true inline. Escape and the outside press are the closing stack's and never reach a panel that was never attached; Tab walks through the panel and out the far side, which is the whole point of drawing it in the page. Each is measured there as an absence, in libs/components/popover/src/popover.spec.ts.

Evidence

What the repository holds for this component

Read at build time from the tracked snapshots, not typed here.

70.45%mutation score155 of 220 mutants killed

15 × 3e2e cases × enginesplus the shared audits: axe, forced colors, preferences, size, hydration

3colour pairs measuredlight and dark, at every token build

1visual baselinesChromium, the sandbox's own pictures

3elements in the preview1 listeners · 1 render to settle · 2856 µs in jsdom, held exactly but for the clock

Why it is built this way

It is the dialog minus one word, and every difference follows from that word: no veil, nothing made inert, no scroll lock — the page behind goes on answering, which is the whole point of a panel that hangs off a control instead of standing over the page. What it keeps is the part a panel with content cannot do without: it takes focus, it says what it is, and it hands focus back to the trigger on the way out (0031).

Decisions behind it

0066A panel is a layer or a region, and the consumer says which
0031A panel's tab order belongs to its trigger
0029A modal is an overlay, not a <dialog> — the platform's modal is not composable with ours
0024The overlay layer carries what an overlay severs, and borrows the closing stack
0025A panel says whether it takes focus, and the rest of the focus layer waits for a consumer
0013No headless core / skin split
lesson-93The outside press and the trigger's press are one event
lesson-35The control handed the wrapper its frame but not its panel

Known limitations

One trigger per popover. Focus comes back to "the trigger", so two controls opening one panel would make that "whichever registered last". Reported in dev mode rather than repaired: the fix is a popover each, and the library cannot know which of the two the author meant.
No close button. A dialog draws one because its trigger may be anywhere and the veil hides the page; a popover always has a live trigger beside it, and Escape, a press outside and Tab are three more ways out. A panel that needs an explicit answer puts a button in its own content — (click)="panel.open.set(false)" — which is also why the component carries no string to translate.
It is not a place to park — unless it is inline. Over the page, Tab is a way out, so a panel the user is meant to leave and come back to is not this component (0031). Drawn in the page it is exactly that shape, because the tab order it stands in is the page's own. What still sends a reader to the drawer is the other half of 0047: a drawer is docked to an edge of the window and is still text in the document when it is shut (hidden="until-found", so find-in-page reaches it), where an inline popover is in the flow where it was written and is gone entirely while open is false.
No arrow. A pointer drawn from the panel to the trigger is one more thing to position and repaint on every flip; the 8 px gap and the placement say the same thing more cheaply. The same call as the tooltip's.
A popover inside a popover is not a pattern here. Nothing forbids it and the closing stack orders the two correctly, but the focus return of the inner one lands on a trigger inside the outer one, and nothing measures that arrangement. A menu with submenus is the menu's problem, and it is a different component.

pacit