Jolty home Jolty Documentation


Compact user interface element featuring links and offers keyboard navigability.
<button data-ui-toggle="my-dropdown" class="btn btn--md btn--primary btn--toggler">
    viewBox="0 0 24 24"
    <path stroke-linecap="round" stroke-linejoin="round" d="M19 8.5l-7.25 7.25-7.25-7.25"></path>
<div data-ui-dropdown data-ui-dropdown-mode="absolute" class="dropdown" hidden id="my-dropdown">
  <div data-ui-dropdown-arrow class="dropdown-arrow"></div>
  <button class="dropdown-item" data-ui-dropdown-item>History</button>
  <button class="dropdown-item" data-ui-dropdown-item>Settings</button>
  <button class="dropdown-item" data-ui-dropdown-item>Sign Out</button>

Getting started

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

<button type="button">Account <span></span></button>
<div id="my-dropdown">
  <a href="#">History</a>
  <a href="#">Settings</a>
  <button type="button">Sign Out</button>
History Settings

Next, add the data-ui-dropdown attribute to the <div> and the data-ui-toggle attribute to the <button>, referencing the id we assigned to the dropdown.

Also, for all menu items, set the data-ui-dropdown-item attribute; this will allow navigation between them using the arrow keys on the keyboard.

Then, include the hidden attribute to hide the dropdown by default.

<button data-ui-toggle="my-dropdown">Account <span></span></button>
<div data-ui-dropdown id="my-dropdown" hidden>
  <a href="#" data-ui-dropdown-item>History</a>
  <a href="#" data-ui-dropdown-item>Settings</a>
  <button data-ui-dropdown-item>Sign Out</button>

Next, initialize all components with the data-ui-dropdown attribute.

import { Popover } from "jolty";

Also, let’s toggle the arrow’s state using the CSS class .ui-active.

.dropdown-toggler.ui-active span {
  transform: scaleY(-1);


You might have noticed that there is no gap between the trigger and the dropdown. To introduce an offset, use the CSS variable --ui-dropdown-offset. To align it to the bottom-right corner, use --ui-dropdown-placement.

.dropdown {
  --ui-dropdown-offset: 0.25rem;
  --ui-dropdown-placement: bottom-end;
@screen (min-width:1024px) {
  .dropdown {
    --ui-dropdown-offset: 0.5rem;

Additionally, the placement can be set using the data-ui-dropdown-placement, but it won’t be responsive in this case.


Often, along with a dropdown, an arrow (or sometimes referred to as a triangle or caret) is used, which points towards the button. To create this, use the data-ui-dropdown-arrow attribute.

<div data-ui-dropdown id="my-dropdown" hidden>
  <div data-ui-dropdown-arrow></div>

Next, we’ll set the offset of the dropdown through the CSS variable --ui-dropdown-arrow-offset and the margin from the edge using --ui-dropdown-arrow-padding.

By default, the arrow extends beyond the bounds of the dropdown by 50% of its size, hence --ui-dropdown-arrow-offset is set to 0, and there’s no need to specify it.

.dropdown {
  --ui-dropdown-arrow-offset: 0;
  --ui-dropdown-arrow-padding: 1rem;
.dropdown-arrow {
  position: absolute;
  top: 0;
  left: 0;
  translate: var(--ui-dropdown-arrow-left) var(--ui-dropdown-arrow-top);
  background-color: inherit;
  width: 0.4rem;
  aspect-ratio: 1;
  rotate: 45deg;


Given that we’re using the Popover API and the Dialog element, the dropdown supports the native backdrop through the ::backdrop pseudo-element wrapped within data-ui-floating. This means we can employ the :has() pseudo-class to determine the specific content within the dropdown and decide whether to display the backdrop.

[data-ui-floating="dropdown"]::backdrop {
  background-color: rgb(17 24 38 / 0.2);
  opacity: 1;

You can also add a class to the wrapper using the floatingClass option.

<div data-ui-dropdown data-ui-floating-class="backdrop:bg-black/20" id="my-dropdown" hidden>


For animating the dropdown, we can use specific CSS classes added during the opening and closing process of the dropdown. It’s also recommended to use the CSS variable --ui-dropdown-transform-origin so that the dropdown’s transformation is relative to its placement.

.dropdown {
  &.ui-leave-active {
    transition-duration: 200ms;
    transition-property: opacity, scale;
    transition-timing-function: ease-in-out;
    transform-origin: var(--ui-dropdown-transform-origin);
  &.ui-leave-to {
    opacity: 0;
    scale: 0.95;

Animating the backdrop is a bit more complicated. Since it’s not a child element of dropdown, we need to animate its pseudo-element ::backdrop.

[data-ui-floating="dropdown"]::backdrop {
  transition: all 200ms ease-in-out;
  background-color: rgb(17 24 38 / 0.2);
  opacity: 0;
[data-ui-floating="dropdown"]:has(> .ui-active)::backdrop {
  opacity: 1;


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

<button data-ui-toggle="my-dropdown">Account <span></span></button>
<div data-ui-dropdown data-ui-trigger="click hover" id="my-dropdown" hidden>My dropdown</div>

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


The dropdown can be opened in three modes. This can be achieved using the data-ui-dropdown-mode attribute.

ModeTagAutofocusFocus TrapTop Layer
'dialog'<dialog>Always yes (native)NoYes
'modal'<dialog>Always yes (native)Always yes (native)Always yes (native)


Let’s create a dropdown that, when clicking on a button with data-action="delete" attribute, will display a message asking for confirmation.

<button data-ui-toggle="my-dropdown">Action <span></span></button>
<div data-ui-dropdown id="my-dropdown" hidden>
  <button data-ui-dropdown-item data-action="view">View</button>
  <button data-ui-dropdown-item data-action="edit">Edit</button>
  <button data-ui-dropdown-item data-action="delete">Delete</button>
const dropdownElem = document.getElementById("my-dropdown");
dropdownElem?.addEventListener("ui-dropdown:hide", ({ detail: [popover, { trigger }] }) => {
  if (trigger?.dataset?.action === "delete") {
    confirm(`Are you sure you want to delete it?`);

You can also listen to the event on the document. This behavior can be turned off by setting {eventBubble: false}.

document.addEventListener("ui-dropdown:hide", ({ detail: [dropdown, { event, trigger }] }) => {
  if ( === "my-dropdown" && trigger?.dataset?.action === "delete") {
    confirm(`Are you sure you want to delete it?`);


However, what if you have multiple dropdowns 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-dropdown and data-action attribute for our example.

<button data-ui-toggle="my-dropdown">Action <span></span></button>
<div data-ui-dropdown="my-dropdown" id="my-dropdown" hidden>
  <button data-ui-dropdown-item data-action="view">View</button>
  <button data-ui-dropdown-item data-action="edit">Edit</button>
  <button data-ui-dropdown-item data-action="delete">Delete</button>
js"action", (dropdownElem) => {
  return {
    toggler: dropdownElem.previousElementSibling,
    items: "[data-action]",
    async itemClickHide({ trigger, dropdown }) {
      if (trigger.dataset.action === "delete") {
        if (!confirm(`Are you sure you want to delete it?`)) return;
        // await something();
        return false;
      return true;

If the group is not declared through, then the dropdown won’t be initialized after calling Dropdown.initAll().

Also, if an empty string '' is passed instead of a name or skip it, then the provided settings will apply to all dropdowns with the data-ui-dropdown attribute where no name is specified.

// or => ({}));


initBooleantrueShould the instance be automatically initialized when an instance is created? If false, you’ll need to manually initiate it by calling dropdown.init().
destroyBooleanfalseAllows you to destroy an instance at a specific breakpoint.
dataString''Allows you to use the default options that have been added through 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-dropdown:'Prefix for events dispatched on the dropdown 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.
shownBooleannullDetermines if the dropdown is expanded after initialization. By default, it’s null, which means it checks the hidden attribute or another attribute, depending on hideMode.
awaitAnimationBooleanfalseDetermines whether to wait for the end of the animation to trigger 'shown','hidden' events and return a promise.
escapeHideBooleantrueWhether to close the dropdown when the Escape key is pressed.
outsideHideBooleantrueWhether to close the dropdown when clicking outside of it.
togglerClassActiveString'ui-active'CSS class for toggler when dropdown is open.
dropdownClassActiveString'ui-active'CSS class for dropdown when it’s open.
floatingClassString''Adds a CSS class for the floating wrapper around the dropdown. Attribute: data-ui-floating-class
triggerString'click'dropdown supports triggers by 'click' and 'hover'. You may pass multiple triggers; separate them with a space. Attribute: data-ui-trigger
modeStringfalseSets the way the dropdown is displayed, supports 3 display modes - false, 'dialog' and 'modal' to create a focus trap. Attribute: data-ui-mode
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 dropdown.
preventScrollBooleanfalseDefines whether the CSS class .ui-prevent-scroll should be added to the <html> element when the dropdown 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
dismissBoolean, CSSSelectortrueAllows the dropdown 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="dropdown"]' is clicked.
autofocusBoolean, CSSSelector, ElementtrueDefines the element that should be focused when the dropdown is opened. By default it’s true, meaning the '[autofocus],[data-ui-autofocus]' element will be focused.
itemsCSSSelector, Element[], Function'[data-ui-dropdown-item]'Defines the elements that can be focused by keyboard arrows.
arrowActivationString'y'Determines which arrow keys should open the dropdown when pressed. Supports the values 'x','y','left','right','up','down'.
itemClickHideBoolean, Function, CSSSelector, Element, Element[]trueDefines whether the dropdown should be closed when an item is clicked. Also accepts a function that returns a boolean value ({trigger, dropdown, event}) => Boolean.
topLayerBooleantrueDetermines whether the popover should be displayed in the top layer. CSS Variable: --ui-dropdown-top-layer: true;
rootElement'body'The element to which the dropdown will be appended.
moveToRootBooleanfalseMoves the dropdown to the element defined in the root option when opened. CSS Variable: --ui-dropdown-move-to-root: false;
a11yBooleantrueAdds aria-controls, aria-expanded and role="button" attributes to the toggler element.
hideModeString'hidden'Accepts one of the next values 'hidden','hidden-until-found','inert','class-hidden','class-shown','remove' Attribute: data-ui-hide-mode
keepPlaceBooleantrueDetermines if the component’s space is preserved when removed by hideMode: 'remove'.

Hide mode

The dropdown can be hidden in several ways using the hideMode option.

ModeHidden stateDescription
'hidden'[hidden]Default mode, hides through display: none;
'hidden-until-found'[hidden="until-found"]The element will show when a match is found in the site search. Read more
'inert'[inert]Makes the element non-interactive, but remains visible
'class-hidden'.ui-hiddenThe element remains fully interactive,
adds the .ui-hidden class when hidden
'class-shown'-The element remains fully interactive,
adds the .ui-shown class when shown
'remove'-The element is removed from the DOM.
Add the hidden attribute to hide by default


placementString'bottom'How to position the dropdown: Use 'top','bottom','left', or 'right'. You can also append '-start' or '-end' to these positions for better alignment of the dropdown, such as 'top-start'.
You can also use the 'dialog' value, in which case the dropdown will be displayed as a dialog, without being attached to the toggler. Attribute: data-ui-placement CSS Variable: --ui-dropdown-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 dropdown and the toggler. CSS Variable: --ui-dropdown-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-dropdown-padding: 0px;
flipBoolean, Booleantruewhether the dropdown 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-dropdown-flip: true;
stickyBooleantrueDefines whether the dropdown should shift to stay in view during a scroll. CSS Variable: --ui-dropdown-sticky: true;
shrinkBooleanfalseDefines whether the dropdown 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-dropdown-shrink: false;
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-dropdown-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-dropdown-arrow element. CSS Variable: --ui-dropdown-arrow-width: 0px;
heightNumber0Sets the height of the arrow. By default, it gets the height of the data-ui-dropdown-arrow element. CSS Variable: --ui-dropdown-arrow-height: 0px;
offsetNumber0Sets the arrow’s offset from the dropdown. CSS Variable: --ui-dropdown-arrow-offset: 0px;
paddingNumber0Sets padding from the dropdowns’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-dropdown-arrow-padding: 0px;


transitionString, Boolean, TransitionOptionstrueObject with transition options or string to set the name option for the transition.
nameString'ui'Defines the name of the transition that will be used to apply CSS rules. Attribute: data-ui-transition-name
cssBooleantrueDefines if the transition should be applied using CSS rules.
cssVariablesBooleanfalseAdds special CSS variables during the transition to the dropdown element and removes them after completion.
enterFunctionnullAccepts a function enter(el, done){}. call the done() callback to indicate transition end
enterActiveString, Object''CSS classes or styles applied during the entire entering phase. Attribute: data-ui-enter-active
enterFromString, Object''CSS classes or styles applied at the start of the entering phase. Attribute: data-ui-enter-from
enterToString, Object''CSS classes or styles applied at the end of the entering phase. Attribute: data-ui-enter-to
leaveFunctionnullAccepts a function leave(el, done){}. call the done() callback to indicate transition end
leaveActiveString, Object''CSS classes or styles applied during the entire leaving phase. Attribute: data-ui-leave-active
leaveFromString, Object''CSS classes or styles applied at the start of the leaving phase. Attribute: data-ui-leave-from
leaveToString, Object''CSS classes or styles applied at the end of the leaving phase. Attribute: data-ui-leave-to
durationNumbernullDefines the duration of the transition. Should be used only when the animation occurs on child elements.

If the cssVariables option is enabled, special CSS variables are added during the transition to collapse and are removed after its completion.

--ui-transition-widthNumberThe width of the element at the start of the transition.
--ui-transition-heightNumberThe height of the element at the start of the transition.

CSS Variables

--ui-dropdown-widthNumberThe width of the dropdown.
--ui-dropdown-heightNumberThe height of the dropdown.
--ui-dropdown-anchor-widthNumberThe width of the toggler.
--ui-dropdown-anchor-heightNumberThe height of the toggler.
--ui-dropdown-available-widthNumberThe remaining width between the toggler and the boundary edge.
Only when the shrink option is enabled.
--ui-dropdown-available-heightNumberThe remaining height between the toggler and the boundary edge.
Only when the shrink option is enabled.
--ui-dropdown-arrow-leftNumberThe left offset for the arrow.
--ui-dropdown-arrow-topNumberThe top offset for the arrow.
--ui-dropdown-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 through the attribute data-ui-dropdown="name".
updateDefault(options)optionsUpdates default options.
initAll(root)instanceSearches for elements in root, which defaults to document with the attribute data-ui-dropdown 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 / dropdown 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, dropdownElementAll components have a base property, which refers to the element through which the component is initialized and where events are fired. dropdown is the same as base.
isOpenBooleanIndicates whether the dropdown is currently shown.
initialPlaceNodeNodeReference to the node that is located where the dropdown was at the moment of initialization.

Class properties

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


By default, events that are listened to directly through an element have the prefix 'ui-dropdown:'. This can be changed through the eventPrefix property. Additionally, you can disable the bubbling of these events using eventBubble or turn them off entirely via eventDispatch."my-dropdown", {
  on: {
    shown(instance, { trigger, event }) {
      // do something...
    any(eventName, instance, { trigger, event }) {
      if (eventName === "shown") {
        // do something...
// or directly on the dropdown element
const dropdownElem = document.querySelector(".my-dropdown");
dropdownElem.addEventListener("ui-dropdown:show", (e) => {
  const [instance, { trigger, event }] = e.detail;
  // do something...
// or on the document
document.addEventListener("ui-dropdown:show", (e) => {
  const [instance, { trigger, event }] = e.detail;
  // do something...
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.
2023 © A Project by Jolty Labs 🇪🇸 🇺🇦