jb-popover

Responsive web component: an anchored popover on desktop, a centered tablet panel, and a draggable bottom sheet on mobile.

Examples | React wrapper | Styling

Installation

npm i jb-popover

import 'jb-popover';

const popover = document.querySelector('jb-popover');
popover.bindTarget(document.querySelector('#trigger'));
popover.open();

<button id="trigger">Choose a value</button>
<jb-popover aria-label="Choose a value">
  <div>Your content</div>
</jb-popover>

API reference

Options are JavaScript properties, not HTML attributes, unless listed as attributes below.

Attributes

| Attribute | Meaning | | --- | --- | | is-open | Boolean attribute parsed by jb-core; opens or requests an animated close. | | id | Enables an owned URL hash entry when opened in mobile/tablet mode. | | aria-label | Accessible label for the internal dialog when modal behavior is active. |

Properties

| Property | Type | Default | Meaning | | --- | --- | --- | --- | | isOpen | boolean (read-only) | false | Remains true through dismissal; false when the closed event fires. | | isMobileMode | boolean (read-only) | viewport | True at widths up to 48rem, including tablets. | | isBottomSheet | boolean (read-only) | viewport | True at widths up to 40rem. | | positionArea | { inline?, block? } | { inline: 'start', block: 'after' } | Preferred desktop anchor alignment; partial assignments preserve other fields. | | autoPlacement | boolean | true | Flip above/below when the opposite side has more room and shift inside the viewport with an 8px margin. | | swipeToClose | boolean | true | Allow downward dismissal from the handle or backdrop on bottom sheets. | | dragFromContent | boolean | false | Also allow eligible gestures starting in content. | | modal | boolean or 'auto' | 'auto' | Auto enables modal behavior on mobile/tablet and leaves desktop non-modal. | | closeOnEscape | boolean | true | Allow Escape to request dismissal of the topmost popover. | | restoreFocus | boolean | false | Restore previous focus on close; opt in only for triggers that do not open on focus. | | autoCloseOnBackgroundClick | boolean | true | Automatically close after an allowed backdrop-click request. | | overflowHandler | 'NONE' or 'SLIDE' | 'NONE' | Legacy desktop hover correction. Prefer automatic placement for viewport collisions. | | overflowDom | HTMLElement or null | null | Boundary for legacy overflow correction; otherwise uses the viewport. | | PopoverHashPath | string or null (read-only) | from id | Hash path for this instance. | | JBID | symbol (read-only) | unique | Instance identifier. |

Methods

| Method | Behavior | | --- | --- | | open() | Opens, positions, activates observers, and applies modal/history behavior. Interrupts an in-progress dismissal. | | close() | Animates dismissal without dispatching a close request. Emits closed on completion. | | bindTarget(element) | Bind or replace the desktop anchor, including while already open. | | unBindTarget() | Remove the anchor and its observers. | | checkInitialOpenness() | Check whether the URL hash addresses this popover; called on connection. |

Events

| Event | Detail | Behavior | | --- | --- | --- | | load | none | Component connected, before internal listeners are registered. | | init | none | Connection initialization completed. | | url-open | none | The current URL hash caused opening. | | before-close | { eventType } | Cancelable request for swipe, backdrop, or Escape dismissal. | | close | { eventType } | Follows an allowed request; also cancelable for swipe/backdrop/Escape. Browser-back dispatches a notification. | | closed | none | Non-cancelable completion event after any animated close, including programmatic close. |

Dismissal events bubble and cross shadow boundaries. The close event is a request/notification, not animation completion.

event.detail.eventType identifies the trigger:

| Value | Trigger | | --- | --- | | SWIPE_DOWN | A downward drag or flick crossed the dismissal threshold. | | BACKGROUND_CLICK | The mobile/tablet backdrop was clicked. | | ESCAPE_KEY | Escape was pressed while this was the topmost popover. | | HISTORY_BACK_EVENT | Navigation left this instance's owned history entry. | | OUTSIDE_CLICK, CLOSE_BUTTON_CLICK | Reserved legacy reasons. |

Use event.preventDefault() synchronously to reject a request. A rejected swipe returns smoothly. For asynchronous confirmation, prevent first and call close() after confirmation.

popover.addEventListener('before-close', event => {
  if (hasUnsavedChanges) event.preventDefault();
  console.log(event.detail.eventType);
});
popover.addEventListener('closed', () => {
  console.log('Dismissal animation finished');
});

Open and close

popover.open();
popover.close(); // starts the exit animation

isOpen remains true until exit completes. Calling open() during exit cancels the dismissal. Reduced-motion preferences remove timed movement. Do not remove the element before closed if you want its exit animation to finish.

Anchor position

Supported inline values: start, end, center, center-before, center-after. Supported block values: before, after. Inline alignment follows the anchor's text direction.

popover.positionArea = { inline: 'end', block: 'before' };
popover.autoPlacement = false; // use the requested alignment exactly

Anchor height/width changes, nested scroll containers, and shadow-root scroll ancestors are observed while open. Rebinding or reconnecting restores observation. Transformed containing blocks are included in coordinate calculations. Scroll-driven work is batched before repaint; closed popovers do not measure anchors on resize.

Overflow handling

autoPlacement adjusts placement against the viewport. The legacy overflowHandler = 'SLIDE' shifts content upward on desktop mouse enter, using overflowDom when supplied; mouse leave restores it.

Mobile swipe dismissal

At widths up to 40rem, drag from the handle, non-content sheet area, or anywhere on the backdrop. Drag beyond 30% of sheet height or flick downward to close. Content and backdrop follow the finger. A returning sheet can be grabbed again without jumping to its origin.

dragFromContent is disabled by default. If enabled, every scrollable ancestor must already be at the top when the touch starts. Reaching the top by scrolling requires a new gesture. Interactive controls and horizontal gestures are excluded.

<jb-popover aria-label="Choose a date">
  <div data-jb-popover-no-drag>Place a calendar or swiper here.</div>
</jb-popover>

data-jb-popover-no-drag excludes the marked content region and its descendants. swipeToClose = false disables all sheet dragging. Tablet and desktop layouts do not use touch dismissal.

Modal behavior and accessibility

With modal = 'auto', mobile and tablet overlays lock page scrolling, make surrounding content inert, contain keyboard focus, and expose an internal role="dialog" with aria-modal="true". Supply aria-label to name the dialog. Initial focus goes to the first focusable content element with autofocus, or the content container when none exists, before the background becomes inert. Set restoreFocus = true to restore previous focus on close. It defaults to false so focus-triggered pickers do not reopen after selection.

Set modal = false for non-modal pickers that need to retain input focus, or modal = true to opt into these behaviors on desktop. Desktop is non-modal by default. Escape targets the topmost popover; nested modal popovers keep scrolling locked until the final modal closes. These popovers coordinate with each other, not an application's independent overlay manager.

The sheet accounts for safe-area insets and visual-viewport height/offset changes, including space taken by a virtual keyboard. Oversized mobile content remains scrollable.

Mobile URL hash state

An id enables a history entry when an open popover enters mobile/tablet mode. Router state fields are preserved. Once created, the entry remains owned through a resize back to desktop, so browser back still dismisses it. An existing matching deep link is not pushed again.

Closing consumes only the current entry owned by this instance. Disconnecting restores the previous URL/state for a current owned entry without navigating away. Avoid assigning the same id to multiple popovers. Browser-back remains a notification and does not use before-close.

CSS parts and variables

| Part | Purpose | | --- | --- | | content | Sheet/panel content container. | | drag-handle | Bottom-sheet drag area. | | backdrop | Independent overlay background, blur, and fade. |

| CSS variable | Purpose | | --- | --- | | --jb-popover-z-index | Stacking order. | | --jb-popover-bg-color | Content background. | | --jb-popover-back-bg-color | Backdrop background. | | --jb-popover-handle-color | Drag indicator color. | | --jb-popover-border-radius | Content corner radius. | | --jb-popover-padding | Desktop content padding. | | --jb-popover-box-shadow | Content shadow. | | --jb-popover-top | Unanchored desktop top position. | | --jb-popover-margin-top | Desktop top margin. |

jb-popover::part(backdrop) {
  background: rgb(0 0 0 / 40%);
  backdrop-filter: blur(8px);
}

Tests

From the design-system repository root, run deno task test --name=jb-popover. This builds the package, checks formatting/types, and runs the popover Storybook and browser suites. See test details.