Orbit

Zero-dependency mixin for creating Web Component popovers.

npm install @blueprintui/orbit

GitHub

NPM

PopoverMixin

The PopoverMixin provides popover functionality for any Web Component. It uses the native Popover API with CSS Anchor Positioning.

import { PopoverMixin } from '@blueprintui/orbit/popover';

class MyPopover extends PopoverMixin(HTMLElement) {
  connectedCallback() {
    super.connectedCallback();
  }
}

customElements.define('my-popover', MyPopover);

<button popovertarget="my-popover">show</button>
<my-popover id="my-popover">content</my-popover>

show popover

basic popover content

CSS Anchor Positioning

Popovers automatically anchor to their trigger element using CSS Anchor Positioning. You can optionally set the anchor position using the anchor attribute/property to anchor to another element that is not the trigger element.

<button id="anchor-trigger" popovertarget="demo-anchor">
  anchored popover
</button>
<demo-anchor id="demo-anchor" anchor="anchor-trigger">
  anchored below the button
</demo-anchor>

demo-anchor {
  position: fixed;
  position-area: bottom span-right;
  margin-top: 8px;
}

anchored popover

anchored below the button

Tooltip (Hint)

Use the hint popover type with the Interest Invokers API for tooltips that appear on hover/focus.

class DemoTooltip extends PopoverMixin(HTMLElement) {
  get popoverConfig() {
    return {
      type: 'hint',
      modal: false,
      focusTrap: false,
      scrollLock: false
    };
  }
}

<button interestfor="demo-tooltip">hover for tooltip</button>
<demo-tooltip id="demo-tooltip">tooltip text</demo-tooltip>

hover for tooltip

Modal Dialog

Enable modal, focusTrap, and scrollLock for dialog-style popovers.

class DemoModal extends PopoverMixin(HTMLElement) {
  get popoverConfig() {
    return {
      type: 'auto',
      modal: true,
      focusTrap: true,
      scrollLock: true
    };
  }
}

show modal

Popover API

The Popover API enables declarative popover control with popovertarget.

<button popovertarget="popover">toggle</button>
<button popovertarget="popover" popovertargetaction="show">show</button>
<button popovertarget="popover" popovertargetaction="hide">hide</button>

toggle

show

hide

Invoker Commands API

The Invoker Commands API provides command-based control.

<button commandfor="popover" command="toggle-popover">toggle</button>
<button commandfor="popover" command="show-popover">show</button>
<button commandfor="popover" command="hide-popover">hide</button>

toggle

show

hide

controlled via commands api

Events

Listen to open and close events on popover elements. The toggle and beforetoggle events are native to the Popover API. The open and close events are Custom Events fired by the PopoverMixin.

popover.addEventListener('toggle', () => console.log('toggle'));
popover.addEventListener('beforetoggle', () => console.log('beforetoggle'));
popover.addEventListener('open', () => console.log('open'));
popover.addEventListener('close', () => console.log('close'));

toggle popover

open and close to see events

Events:

Programmatic Control

Use showPopover(), hidePopover(), and togglePopover() methods.

popover.showPopover();
popover.hidePopover();
popover.togglePopover();

showPopover()

hidePopover()

togglePopover()

controlled programmatically

API

PopoverMixin

Apply to any HTMLElement subclass to add popover functionality.

import { PopoverMixin } from '@blueprintui/orbit/popover';

class MyPopover extends PopoverMixin(HTMLElement) {
  get popoverConfig() {
    return {
      type: 'auto',      // 'auto' | 'manual' | 'hint'
      modal: false,      // Show backdrop, set aria-modal
      focusTrap: false,  // Trap focus within popover
      scrollLock: false  // Prevent page scroll
    };
  }
}

Properties

Property	Type	Description
`open`	`boolean`	Controls popover visibility
`anchor`	`string \| HTMLElement`	Anchor element ID or reference
`popoverConfig`	`PopoverConfig`	Configuration options (override getter)

Events

Event	Description
`toggle`	Fired when popover is toggled
`beforetoggle`	Fired before popover is toggled
`open`	Fired when popover opens
`close`	Fired when popover closes

Native Popover Type Behaviors

Behavior	auto	hint	manual
Escape key closes	✅	✅	❌
Click outside closes	✅	✅	❌
Opens → closes other auto	✅	❌	❌
Multiple can coexist	⚠️ nested only	⚠️ with auto	✅

Common Popover Behaviors

Component	Popover Type	Focus Trap	Modal Default	Scroll Lock
Tooltip	`hint`	❌	❌	❌
Toggletip	`auto`	❌	❌	❌
Toast	`manual`	❌	❌	❌
Dropdown	`auto`	⚠️ managed	❌	❌
Drawer	`auto`	✅	✅	✅
Dialog	`auto`	✅	✅	✅