rc-popover

Anchored non-modal surface around a native trigger and consumer-owned content. It supplies placement, open-state control, and a Popover API fallback; content semantics and interaction remain the author's responsibility.

Package

@rcarls/rc-popover

Element

<rc-popover>

Native dependency

Consumer-owned trigger and content

State model

Controlled or uncontrolled open state

Main events

rc-popover-toggle

Related

Usage rulesTheme previews

Installation

npm

npm install @rcarls/rc-webcomponents@next

Yarn

yarn add @rcarls/rc-webcomponents@next

pnpm

pnpm add @rcarls/rc-webcomponents@next

import '@rcarls/rc-webcomponents/rc-popover/define';

Usage

Keep the trigger and surface as direct children. Native popovertarget and popover make the panel operable before upgrade. Give interactive content an appropriate role and accessible name; rc-popover does not assign one.

<rc-popover placement="block-end-start">
  <button slot="trigger" type="button" popovertarget="settings-panel" aria-haspopup="dialog">
    Settings
  </button>
  <section
    slot="content"
    id="settings-panel"
    popover
    role="dialog"
    aria-labelledby="settings-title"
  >
    <h2 id="settings-title">Display settings</h2>
    <label><input type="checkbox" /> Show details</label>
  </section>
</rc-popover>

A button trigger toggles by default. Set trigger-action="none" for a panel controlled by application state or by optional open-on-hover and open-on-focus. Escape closes an open panel; a click outside also closes it. Focus inside the panel stays usable, and Escape returns focus to the trigger when focus was in the panel. open is a silent controlled host property; default-open initializes uncontrolled state. User requests dispatch rc-popover-toggle with {open}.

Material rich tooltip recipe

The Material theme styles this optional composition. Use a named non-modal dialog when the content has a link or button; a role="tooltip" must not contain focusable controls. The data-rc-material-rich-tooltip marker is a public theme opt-in. Direct h2, p, and optional footer children receive title, body, and action spacing. The author controls the action's behavior.

<rc-popover data-rc-material-rich-tooltip open-on-hover open-on-focus>
  <button slot="trigger" type="button" popovertarget="feature-tip" aria-haspopup="dialog">
    Feature info
  </button>
  <section
    slot="content"
    id="feature-tip"
    popover
    role="dialog"
    aria-labelledby="feature-tip-title"
  >
    <h2 id="feature-tip-title">Export presets</h2>
    <p>Save your export settings for next time.</p>
    <footer><a href="/help/presets">Learn more</a></footer>
  </section>
</rc-popover>

Keep essential instructions visible without hover. For concise, non-interactive descriptions, use rc-tooltip instead.

Live demo

Accessibility

The element keeps the trigger's aria-expanded and aria-controls in step with open, and restores the author's own values when it lets go of the trigger. Escape closes an open popover and returns focus to the trigger. Give the popover content its own semantics, such as a heading or a labeled dialog, when it is more than a hint.

API

Properties

Property	Markup	Type	Default	Description
placement	placement	RCPopoverPlacement	'block-end-start'	Preferred logical placement.
triggerAction	trigger-action	RCPopoverTriggerAction	'toggle'	Whether trigger activation toggles the surface.
openOnHover	open-on-hover	boolean	false	Open while the pointer is over trigger or content.
openOnFocus	open-on-focus	boolean	false	Open while focus is within trigger or content.
open	open	boolean	Not specified	Controlled open state. A host write never emits `rc-popover-toggle`.
defaultOpen	default-open	boolean	Not specified	Initial open state used until the host or user changes the state.

Events

Event	Detail type	Description
rc-popover-toggle	CustomEvent	User requested open-state change; detail: `{open: boolean}`.

Slots

Name	Description
trigger	Direct child native trigger, usually a `<button>`.
content	Direct child popover surface with author-owned semantics.

CSS Custom Properties

Property	Default	Description
--rc-popover-max-inline-size	min(20rem, 100dvi - 1rem)	Maximum inline size.
--rc-popover-max-block-size	calc(100dvb - 1rem)	Maximum block size.
--rc-popover-padding-block	0.75rem	Block padding.
--rc-popover-padding-inline	0.75rem	Inline padding.
--rc-popover-border	var(--rc-popup-border)	Surface border.
--rc-popover-radius	var(--rc-popup-radius)	Corner radius.
--rc-popover-background	var(--rc-popup-background)	Surface background.
--rc-popover-color	var(--rc-popup-color)	Surface text color.
--rc-popover-shadow	var(--rc-popup-shadow)	Surface shadow.
--rc-popover-z-index	1	Fallback stacking order.

CSS Parts

Part	Description
root	Shadow wrapper for the two slots.