Jolty UI Jolty UI Documentation Icons Colors


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

Getting started

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

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


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.

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

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

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

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


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

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


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.

<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>
Popover.get('my-popover')?.on("confirm", (popover, { event, trigger }) => {

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,

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.

<button data-ui-toggle="my-popover">Click me <span></span></button>
<div data-ui-popover="confirm" data-ui-modal id="my-popover" hidden>
  <button data-ui-confirm>Yes</button>
  <button data-ui-dismiss data-ui-autofocus>No</button>
js"confirm", (popoverElem) => {
  return {
    toggler: popoverElem.previuosElementSibling,
    modal: true,
    on: {
      confirm(instance) {


initBooleantrueShould the instance be automatically initialized when an instance is created? If false, you’ll need to manually initiate it by calling popover.init().
destroyBooleanfalseAllows you to destroy an instance at a specific breakpoint.
dataString''Allows you to use the default options that have been added by the static method.
onObjectnullUsed to register event handlers.
appearBooleannullIf you want to apply a transition upon initialization as well, you can set this option to true. Attribute: data-ui-appear
eventPrefixString'ui-popover:'Prefix for events dispatched on the popover element.
eventDispatchBooleantrueDefines if events are dispatched or used only within options.
eventBubbleBooleantrueDefines if events should bubble up the DOM.
breakpointsObjectnullDefines custom options for specific breakpoints.
shownBooleannullDefines 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.
awaitAnimationBooleanfalseDetermines whether to wait for the end of the animation to trigger 'shown','hidden' events and return a promise.
backDismissBooleantrueDefines whether the element should close when the Esc key is pressed. Attribute: data-ui-back-dismiss
lightDismissBoolean, ObjecttrueDefines 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
togglerClassActiveString'ui-active'CSS class for toggler when popover is open.
popoverClassActiveString'ui-active'CSS class for popover when it’s open.
triggerString'click'popover supports triggers by 'click' and 'hover'. You may pass multiple triggers; separate them with a space. Attribute: data-ui-trigger
modalBooleanfalseIf 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
returnFocusBooleantrueDefines 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.
focusTrapBooleanfalseDefines whether the focus must be trapped inside the popover.
preventScrollBooleanfalseDefines 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
confirmCSSSelector, Element, Element'[data-ui-confirm]'Sets the element, clicking on which triggers the confirm event.
titleCSSSelector, Element'[data-ui-popover-title]'Sets the element that will be linked to the popover via the aria-labelledby attribute.
descriptionCSSSelector, Element'[data-ui-popover-description]'Sets the element that will be linked to the popover via the aria-describedby attribute.
dismissBoolean, CSSSelectortrueAllows 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.
autofocusBoolean, CSSSelector, ElementtrueDefines 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.
itemsCSSSelector, Element[], Function'[data-ui-popover-item]'Defines the elements that can be focused by keyboard arrows.
arrowActivationString'y'Determines which arrow keys should open the popover when pressed. Supports the values 'x','y','left','right','up','down'.
itemClickHideBoolean, Function, CSSSelector, Element, Element[]trueDefines whether the popover should be closed when an item is clicked. Also accepts a function that returns a boolean value (instance, {trigger, event}) => Boolean.
topLayerBooleantrueDetermines whether the popover should be displayed in the top layer. CSS Variable: --ui-popover-top-layer: 1;
rootElement'body'The element to which the popover will be appended.
moveToRootBooleanfalseMoves the popover to the element defined in the root option when opened. CSS Variable: --ui-popover-move-to-root: 0;
a11yBooleantrueAdds aria-controls, aria-expanded and role="button" attributes to the toggler element.
stateModeString'hidden'Accepts one of the next values 'hidden','hidden-until-found','inert','class-hidden','class-shown','remove' Attribute: data-ui-hide-mode
keepPlaceBooleantrueDefines 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.


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


placementString'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;
delayNumber[150, 0]Sets delay when trigger:'hover'. Accepts 2 values, for mouseevent and mouseleave, if one value is set, it applies to both.
offsetNumber0Specifies the offset between the popover and the toggler. CSS Variable: --ui-popover-offset: 0px;
paddingNumber, Number0Specifies 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;
flipBoolean, Booleantruewhether 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;
stickyBooleantrueDefines whether the popover should shift to stay in view during a scroll. CSS Variable: --ui-popover-sticky: 1;
shrinkBooleanfalseDefines 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;
boundaryOffsetNumber, Number[], Object0Specifies 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;


arrowBoolean, ObjecttrueObject with arrow options or false to disable.
widthNumber0Sets 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;
heightNumber0Sets 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;
offsetNumber0Sets the arrow’s offset from the popover. CSS Variable: --ui-popover-arrow-offset: 0px;
paddingNumber0Sets 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

--ui-floating-widthNumberThe width of the popover.
--ui-floating-heightNumberThe height of the popover.
--ui-floating-anchor-widthNumberThe width of the toggler.
--ui-floating-anchor-heightNumberThe height of the toggler.
--ui-floating-available-widthNumberThe remaining width between the toggler and the boundary edge.
Only when the shrink option is enabled.
--ui-floating-available-heightNumberThe remaining height between the toggler and the boundary edge.
Only when the shrink option is enabled.
--ui-floating-arrow-leftNumberThe left offset for the arrow.
--ui-floating-arrow-topNumberThe top offset for the arrow.
--ui-floating-transform-originNumberThe transform-origin computed from the content and arrow position


init()instanceInitializes the component.
destroy(destroyOptions)instance, nullDestroys the component and accepts an object as a option { remove: false, keepInstance: false, keepState: false }.
update(options)instanceAccepts options as an argument and updates the component.
toggle(toggleOptions, force)promiseToggles 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)promiseOpens the component and accepts the same options as the toggle() method.
hide(toggleOptions)promiseCloses the component and accepts the same options as the toggle() method.

Class Methods

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


idStringThe id of the base / popover element.
isInitBooleanIndicates whether the instance is already initialized.
optsObjectContains the currently applied options for the current breakpoint.
baseOptsObjectContains all options, including the breakpoints option.
base, popoverElementAll 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.
isOpenBooleanIndicates whether the popover is currently shown.
initialPlaceNodeNodeReference to the node that is located where the popover was at the moment of initialization.

Class properties

DefaultObjectContains the default options for all instances.
instancesMapA Map that contains all instances of the Popover class.


beforeInitinstanceEvent will fired right before initialization.
initinstanceFires when initialization has been completed.
beforeShowinstance, {trigger, event}Fires immediately when the show() method is called.
showinstance, {trigger, event}Fires when the element becomes visible, but the CSS transition hasn’t started yet.
showninstance, {trigger, event}Fires when the CSS transition hasn’t been completed.
beforeHideinstance, {trigger, event}Fires immediately when the hide() method is called.
hideinstance, {trigger, event}Fires just before the CSS transition starts.
hiddeninstance, {trigger, event}Fires when the CSS transition has been completed.
beforeDestroyinstanceFires before the instance is destroyed.
destroyinstanceFires immediately when the destroy() method is called.
breakpointinstance, breakpoint, prevBreakpointFires when the breakpoint has been changed.
anyeventName, instanceFires on any event occurrence. The first argument contains the name of the event.
2024 © A Project by Anatolii Moldovanov