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: Theme previews

Installation

npm
Yarn

npm install @rcarls/rc-webcomponents

yarn add @rcarls/rc-webcomponents

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}.

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

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.

Methods

No public methods are documented in the custom elements manifest.

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.

Installation​

Usage​

Material rich tooltip recipe​

Live demo​

API​