Popover

npm install @vrembem/popover

@use "@vrembem/popover";

Popover provides two JavaScript entries depending on how you want to register the custom element.

// Register the <vb-popover> tag as a side-effect
import "@vrembem/popover/define";

// Import the element class directly
import { Popover } from "@vrembem/popover";

// Define the element yourself under a custom namespace
customElements.define("vb-popover", Popover);

Options

Popover is built as a Sass module. Sass options are used to control CSS output, while design token CSS variables control the styling of the component. Below are the available configuration options.

Sass

Popover comes with the following Sass configuration options that can be set using either the config module or Sass with clause methods.

@use "@vrembem/popover" with (
  $config: (
    // Map for outputting popover--width-[key] modifier variants
    // @type map
    "width": (
      "default": 14rem,
      "auto": "fit-content",
      "sm": 10rem,
      "lg": 18rem
    )
  )
);

Design tokens

Popover uses design token CSS variables in a reference and fallback pattern. Variables are referenced in the component's styles but are not directly defined; instead, they are provided with sensible fallbacks.

--vb-popover-width

14rem

--vb-popover-max-width

calc(100vw - 2rem)

--vb-popover-padding

0.5rem

--vb-popover-border

none

--vb-popover-border-radius

var(--vb-border-radius)

--vb-popover-font-size

inherit

--vb-popover-line-height

inherit

--vb-popover-foreground

var(--vb-foreground)

--vb-popover-background

var(--vb-background)

--vb-popover-box-shadow

var(--vb-box-shadow-md)

--vb-popover-drop-shadow

var(--vb-drop-shadow-md)

--vb-popover-transition-property

opacity, display, transform, overlay

--vb-popover-transition-timing-function

var(--vb-transition-timing-function)

--vb-popover-transition-duration

var(--vb-transition-duration-short)

--vb-popover-offset

0.5rem

--vb-popover-margin

1.5rem

--vb-popover-transform-x

0

--vb-popover-transform-y

calc(var(--vb-popover-offset, 0.5rem) * -1)

Basic usage

Vrembem popovers are powered by the native browser popover API and CSS anchor positions. This allows popovers to function without any need for additional JavaScript. For a basic popover, just apply the following attributes along with the .popover class for styling.

<button popovertarget="unique-id">...</button>
<div class="popover" id="unique-id" popover>
  ...
</div>

For tooltips, use the native browser interest invokers API by applying the interestfor attribute on the trigger and popover="hint" on the popover tooltip element.

<button interestfor="unique-id">...</button>
<div class="popover popover--tooltip" id="unique-id" popover="hint">
  ...
</div>

For cases where a trigger uses both a popover and tooltip, you have the <vb-popover> custom element available to help manage this use-case. Import @vrembem/popover/define to register the packaged element, or define your own tag using the exported Popover class. This custom element prevents the tooltip from being displayed while the popover is active.

<vb-popover>
  <button popovertarget="popover-id" interestfor="tooltip-id">...</button>
  <div class="popover" popover id="popover-id">
    ...
  </div>
  <div class="popover popover--tooltip" popover="hint" id="tooltip-id">
    ...
  </div>
</vb-popover>

popover--pos-[key]

A modifier to set the preferred position of a popover relative to its anchor. If not enough space is available in the preferred position, the popover is flipped automatically.

<div id="unique-id" class="popover popover--pos-[key]" popover>
  ...
</div>

Available variants

• popover--pos-bottom
• popover--pos-bottom-start
• popover--pos-bottom-end
• popover--pos-top
• popover--pos-top-start
• popover--pos-top-end
• popover--pos-right
• popover--pos-right-start
• popover--pos-right-end
• popover--pos-left
• popover--pos-left-start
• popover--pos-left-end

popover--arrow

Modifier that adds an arrow to the popover element. When added along with a position modifier, using .popover--arrow will infer the arrow direction. To set an explicit arrow direction, provide a modifier value .popover--arrow-[key].

<!-- Apply the arrow modifier with a position modifier -->
<div id="unique-id" class="popover popover--arrow popover--pos-top" popover="hint">
  ...
</div>

<!-- Set the arrow direction if no position modifier is set -->
<div id="unique-id" class="popover popover--arrow-bottom" popover="hint">
  ...
</div>

Available variants

• popover--arrow
• popover--arrow-top
• popover--arrow-bottom
• popover--arrow-left
• popover--arrow-right

popover--tooltip

To create a tooltip popover, use the interest invoker API along with the .popover--tooltip modifier class for styling. Tooltips appear above their target element by default. Use position modifiers to adjust the position of tooltips.

<button interestfor="unique-id">HTML</button>
<div id="unique-id" popover="hint" class="popover popover--tooltip popover--arrow">
  Hypertext Markup Language
</div>

Popover and interest invoker APIs can be applied to the same anchor. Use the popovertarget and interestfor attributes with the values of their corresponding popover IDs. Use the <vb-popover> custom element in these cases for a better UX when both popover and tooltips are used.

<vb-popover>
  <button popovertarget="unique-id-1" interestfor="unique-id-2">
    ...
  </button>
  <div id="unique-id-1" popover class="popover">
    ...
  </div>
  <div id="unique-id-2" popover="hint" class="popover popover--tooltip">
    ...
  </div>
</vb-popover>

popover--width-[key]

A modifier for adjusting the width of a popover. These modifiers are generated using key/value pairs of the popover-width config options map.

<div id="unique-id" popover class="popover popover--width-sm">
  ...
</div>

Available variants

• popover--width-auto
• popover--width-sm
• popover--width-lg