Popover

Show content over an element with focus trap and CSS-based positioning. Suitable for complex tooltips and context menus.

ARIA design pattern

Getting started

First, create two elements: <button> and <div> with menu items, and assign a unique id to it.

html

<button data-ui-toggle="my-popover">Account</button>
<div class="ui-popover" data-ui-popover id="my-popover" hidden>...</div>

Placement

By default, the popover will be placed below the trigger element. You can change this behavior by adding the data-ui-placement attribute to the popover element.

html

<button data-ui-toggle="my-popover" class="my-popover-btn">Account</button>
<div class="ui-popover" data-ui-popover data-ui-placement="top">...</div>

You can also use CSS variables to set the position by assigning them to the .popover element.

css

.popover {
  --ui-popover-placement: top;
}

Or set the position for the button that triggers the popover; this is convenient when the popover body is located in a different element, for example in the <body>.

css

.my-popover-btn {
  --ui-popover-placement: top;
}

Placement “dialog”

There is also a special dialog mode, in which the popover is not attached to the button, but displayed as a dialog.

css

.popover {
  --ui-popover-placement: dialog;
  /* you can also use @media to set the placement for different breakpoints */
  @media (min-width: 768px) {
    --ui-popover-placement: bottom;
  }
}

Open as a dialog

Trigger

Now, let’s provide the ability to open the popover through 'hover' by adding the attribute data-ui-trigger.

html

<button data-ui-toggle="my-popover">Open popover</button>
<div data-ui-popover data-ui-trigger="click hover" data-ui-placement="top" id="my-popover" hidden>...</div>

For 'hover', it has a delay of 200ms to prevent unintentional opening and closing of the popover. However, this can be modified using the delay.

Events

Upon clicking the data-ui-confirm button, an event 'ui-popover:confirm' is triggered. Its detail contains an Array with instance and an object {event, trigger}. Here, the event value represents the native button click event, while trigger points to the button.

html

<button data-ui-toggle="my-popover">Delete account</button>
<dialog data-ui-popover data-ui-modal id="my-popover" hidden>
  <div data-ui-popover-title>Do you want to delete account?</div>
  <button data-ui-confirm>Cancel</button>
  <button data-ui-dismiss data-ui-autofocus>Delete</button>
</dialog>

Popover.get('my-popover')?.on("confirm", (popover, { event, trigger }) => {
  alert("Confirmed");
  popover.hide();
});

Settings groups

However, what if you have multiple popovers and you don’t want to bind each one with a unique id, but instead wish to set common settings? There’s a static method for that, Popover.data().

You can remove all previously added data-attributes, keeping only the data-ui-popover attribute. By assigning it the name of our popover group, in this case 'confirm', it serves the purpose.

html

<button data-ui-toggle="my-popover">Click me <span>↓</span></button>
<div data-ui-popover="confirm" data-ui-modal id="my-popover" hidden>
  Confirm
  <button data-ui-confirm>Yes</button>
  <button data-ui-dismiss data-ui-autofocus>No</button>
</div>

Popover.data("confirm", (popoverElem) => {
  return {
    toggler: popoverElem.previuosElementSibling,
    modal: true,
    on: {
      confirm(instance) {
        alert("Confirmed");
        instance.hide();
      },
    },
  };
});
 
Popover.initAll();

Options

Name	Type	Default	Description
`init`	`Boolean`	`true`	Should the instance be automatically initialized when an instance is created? If `false`, you’ll need to manually initiate it by calling `popover.init()`.
`destroy`	`Boolean`	`false`	Allows you to destroy an instance at a specific breakpoint.
`data`	`String`	`''`	Allows you to use the default options that have been added by the `Popover.data()` static method.
`on`	`Object`	`null`	Used to register event handlers.
`appear`	`Boolean`	`null`	If you want to apply a transition upon initialization as well, you can set this option to `true`. Attribute: `data-ui-appear`
`eventPrefix`	`String`	`'ui-popover:'`	Prefix for events dispatched on the `popover` element.
`eventDispatch`	`Boolean`	`true`	Defines if events are dispatched or used only within options.
`eventBubble`	`Boolean`	`true`	Defines if events should bubble up the DOM.
`breakpoints`	`Object`	`null`	Defines custom options for specific breakpoints.
`shown`	`Boolean`	`null`	Defines if the popover is expanded after initialization. By default, it’s `null`, which means it checks the `hidden` attribute or another attribute, depending on `stateMode`.
`awaitAnimation`	`Boolean`	`false`	Determines whether to wait for the end of the animation to trigger `'shown','hidden'` events and return a promise.
`backDismiss`	`Boolean`	`true`	Defines whether the element should close when the `Esc` key is pressed. Attribute: `data-ui-back-dismiss`
`lightDismiss`	`Boolean, Object`	`true`	Defines whether the element should close when the user clicks outside of it. You can also pass an object with the option `{contextMenuClick: false}`, which will disable closing the popover when the right mouse button is clicked outside of it. Attribute: `data-ui-light-dismiss`
`togglerClassActive`	`String`	`'ui-active'`	CSS class for `toggler` when `popover` is open.
`popoverClassActive`	`String`	`'ui-active'`	CSS class for `popover` when it’s open.
`trigger`	`String`	`'click'`	popover supports triggers by `'click'` and `'hover'`. You may pass multiple triggers; separate them with a space. Attribute: `data-ui-trigger`
`modal`	`Boolean`	`false`	If the `<dialog>` tag is used, then it opens in modal mode. Also, the properties `focusTrap, backDismiss, lightDismiss, preventScroll`, set to `'auto'` are triggered Attribute: `data-ui-modal`
`returnFocus`	`Boolean`	`true`	Defines whether focus should return to the element that triggered it. You can also pass an object with the option `{await: true}`, which indicates that it should wait for the end of the transition to return focus.
`focusTrap`	`Boolean`	`false`	Defines whether the focus must be trapped inside the `popover`.
`preventScroll`	`Boolean`	`false`	Defines whether the CSS class `.ui-prevent-scroll` should be added to the `<html>` element when the popover is opened. Use thee `--ui-root-scrollbar-width` CSS variable to prevent content shifts when the scrollbar disappears with `overflow: hidden`. Attribute: `data-ui-prevent-scroll`
`confirm`	`CSSSelector, Element, Element`	`'[data-ui-confirm]'`	Sets the element, clicking on which triggers the `confirm` event.
`title`	`CSSSelector, Element`	`'[data-ui-popover-title]'`	Sets the element that will be linked to the popover via the `aria-labelledby` attribute.
`description`	`CSSSelector, Element`	`'[data-ui-popover-description]'`	Sets the element that will be linked to the popover via the `aria-describedby` attribute.
`dismiss`	`Boolean, CSSSelector`	`true`	Allows the popover to be hide when clicked on the button. By default, it’s `true`, meaning the `hide()` method will be called when `'[data-ui-dismiss=""],[data-ui-dismiss="ui-popover"]'` is clicked.
`autofocus`	`Boolean, CSSSelector, Element`	`true`	Defines the element that should be focused when the popover is opened. By default it’s `true`, meaning the `'[autofocus],[data-ui-autofocus]'` element will be focused.
`items`	`CSSSelector, Element[], Function`	`'[data-ui-popover-item]'`	Defines the elements that can be focused by keyboard arrows.
`arrowActivation`	`String`	`'y'`	Determines which arrow keys should open the popover when pressed. Supports the values `'x','y','left','right','up','down'`.
`itemClickHide`	`Boolean, Function, CSSSelector, Element, Element[]`	`true`	Defines whether the popover should be closed when an item is clicked. Also accepts a function that returns a boolean value `(instance, {trigger, event}) => Boolean`.
`topLayer`	`Boolean`	`true`	Determines whether the `popover` should be displayed in the top layer. CSS Variable: `--ui-popover-top-layer: 1;`
`root`	`Element`	`'body'`	The element to which the `popover` will be appended.
`moveToRoot`	`Boolean`	`false`	Moves the `popover` to the element defined in the `root` option when opened. CSS Variable: `--ui-popover-move-to-root: 0;`
`a11y`	`Boolean`	`true`	Adds `aria-controls`, `aria-expanded` and `role="button"` attributes to the toggler element.
`stateMode`	`String`	`'hidden'`	Accepts one of the next values `'hidden','hidden-until-found','inert','class-hidden','class-shown','remove'` Attribute: `data-ui-hide-mode`
`keepPlace`	`Boolean`	`true`	Defines if the component’s space is preserved when removed by `stateMode: 'remove'`.

Hide mode

For more details on how to use, read the State mode section.

Transition

For more details on how to use, read the Transition section.

Floating

Name	Type	Default	Description
`placement`	`String`	`'bottom'`	How to position the `popover`: Use `'top','bottom','left'`, or `'right'`. You can also append `'-start'` or `'-end'` to these positions for better alignment of the popover, such as `'top-start'`. You can also use the `'dialog'` value, in which case the `popover` will be displayed as a dialog, without being attached to the `toggler`. Attribute: `data-ui-placement` CSS Variable: `--ui-popover-placement: bottom;`
`delay`	`Number`	`[150, 0]`	Sets delay when `trigger:'hover'`. Accepts 2 values, for `mouseevent` and `mouseleave`, if one value is set, it applies to both.
`offset`	`Number`	`0`	Specifies the offset between the `popover` and the `toggler`. CSS Variable: `--ui-popover-offset: 0px;`
`padding`	`Number, Number`	`0`	Specifies padding from the anchor’s borders. It accepts two values: padding from the `start` and from the `end`. If a single value is given, it will be applied to both sides. CSS Variable: `--ui-popover-padding: 0px;`
`flip`	`Boolean, Boolean`	`true`	whether the `popover` should flip to the opposite placement when there’s not enough space. It can accept two values, corresponding to the X and Y axes. CSS Variable: `--ui-popover-flip: 1;`
`sticky`	`Boolean`	`true`	Defines whether the `popover` should shift to stay in view during a scroll. CSS Variable: `--ui-popover-sticky: 1;`
`shrink`	`Boolean`	`false`	Defines whether the `popover` should decrease in size to fit when there’s insufficient space. Remember that you must use the generated CSS variables to apply the available sizes. CSS Variable: `--ui-popover-shrink: 0;`
`boundaryOffset`	`Number, Number[], Object`	`0`	Specifies padding from the relative parent’s borders. It can accept up to four values like inset or margin CSS properties. You can also specify an object (for JS only) in the form `{top: 0, right: 0, bottom: 0, left: 0}` CSS Variable: `--ui-popover-boundary-offset: 0px;`

Arrow

Name	Type	Default	Description
`arrow`	`Boolean, Object`	`true`	Object with arrow options or `false` to disable.

`width`	`Number`	`0`	Sets the width of the arrow. By default, it gets the width of the `data-ui-popover-arrow` element. CSS Variable: `--ui-popover-arrow-width: 0px;`
`height`	`Number`	`0`	Sets the height of the arrow. By default, it gets the height of the `data-ui-popover-arrow` element. CSS Variable: `--ui-popover-arrow-height: 0px;`
`offset`	`Number`	`0`	Sets the arrow’s offset from the popover. CSS Variable: `--ui-popover-arrow-offset: 0px;`
`padding`	`Number`	`0`	Sets padding from the popovers’s borders. It accepts two values: padding from the `start` and from the `end`. If a single value is given, it will be applied to both sides. CSS Variable: `--ui-popover-arrow-padding: 0px;`

CSS Variables

Name	Type	Description
`--ui-floating-width`	`Number`	The width of the `popover`.
`--ui-floating-height`	`Number`	The height of the `popover`.
`--ui-floating-anchor-width`	`Number`	The width of the `toggler`.
`--ui-floating-anchor-height`	`Number`	The height of the `toggler`.
`--ui-floating-available-width`	`Number`	The remaining width between the `toggler` and the boundary edge. Only when the `shrink` option is enabled.
`--ui-floating-available-height`	`Number`	The remaining height between the `toggler` and the boundary edge. Only when the `shrink` option is enabled.
`--ui-floating-arrow-left`	`Number`	The left offset for the arrow.
`--ui-floating-arrow-top`	`Number`	The top offset for the arrow.
`--ui-floating-transform-origin`	`Number`	The `transform-origin` computed from the content and arrow position

Methods

Name	Return	Description
`init()`	`instance`	Initializes the component.
`destroy(destroyOptions)`	`instance, null`	Destroys the component and accepts an object as a option `{ remove: false, keepInstance: false, keepState: false }`.
`update(options)`	`instance`	Accepts options as an argument and updates the component.
`toggle(toggleOptions, force)`	`promise`	Toggles the component’s visibility state between shown and hidden. Accepts `true` or `false` as a option, which sets the `animated` option or an object `{ animated: true, silent: false }`.
`show(toggleOptions)`	`promise`	Opens the component and accepts the same options as the `toggle()` method.
`hide(toggleOptions)`	`promise`	Closes the component and accepts the same options as the `toggle()` method.

Class Methods

Name	Return	Description
`toggle(id, force, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `toggle()` method with the specified options.
`show(id, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `show()` method with the specified options.
`hide(id, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `hide()` method with the specified options.
`data(name?, data)`	`Class`	Sets default options for components that have the property `data:'name'` or by the attribute `data-ui-popover="name"`.
`updateDefault(options)`	`options`	Updates default options.
`initAll(root)`	`instance`	Searches for elements in `root`, which defaults to `document` with the attribute `data-ui-popover` and initializes them.
`get(id or elem)`	`instance`	Searches for an instance by `id` or element (checks the `base` property).
`getOrCreate(id or elem, options)`	`instance`	Searches for an instance by `id` or element (checks the `base` property), if not found, creates a new instance with specified options.

Properties

Name	Type	Description
`id`	`String`	The `id` of the `base` / `popover` element.
`isInit`	`Boolean`	Indicates whether the instance is already initialized.
`opts`	`Object`	Contains the currently applied options for the current breakpoint.
`baseOpts`	`Object`	Contains all options, including the `breakpoints` option.
`base, popover`	`Element`	All components have a `base` property, which refers to the element through which the component is initialized and where events are fired. `popover` is the same as `base`.
`isOpen`	`Boolean`	Indicates whether the popover is currently shown.
`initialPlaceNode`	`Node`	Reference to the node that is located where the popover was at the moment of initialization.

Class properties

Name	Type	Description
`Default`	`Object`	Contains the default options for all instances.
`instances`	`Map`	A `Map` that contains all instances of the `Popover` class.

Events

Name	Arguments	Description
`beforeInit`	`instance`	Event will fired right before initialization.
`init`	`instance`	Fires when initialization has been completed.
`beforeShow`	`instance, {trigger, event}`	Fires immediately when the `show()` method is called.
`show`	`instance, {trigger, event}`	Fires when the element becomes visible, but the CSS transition hasn’t started yet.
`shown`	`instance, {trigger, event}`	Fires when the CSS transition hasn’t been completed.
`beforeHide`	`instance, {trigger, event}`	Fires immediately when the `hide()` method is called.
`hide`	`instance, {trigger, event}`	Fires just before the CSS transition starts.
`hidden`	`instance, {trigger, event}`	Fires when the CSS transition has been completed.
`beforeDestroy`	`instance`	Fires before the instance is destroyed.
`destroy`	`instance`	Fires immediately when the `destroy()` method is called.
`breakpoint`	`instance, breakpoint, prevBreakpoint`	Fires when the breakpoint has been changed.
`any`	`eventName, instance`	Fires on any event occurrence. The first argument contains the name of the event.