Tailwind CSS Dropdown Plugin API

Headless, unstyled Dropdown plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

Installation

To get started, install Dropdown plugin via npm, or skip this step if you are already using Preline UI as a package.

Terminal

                        
                          npm i @floating-ui/dom @preline/dropdown

Wrap the dropdown's toggle (your button or link) and the dropdown menu within .relative, or another element that declares position: relative;. Dropdown can be triggered from <a> or <button> elements to better fit your potential needs.

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

                      
                        <div class="hs-dropdown relative inline-flex">
                          <button id="hs-dropdown-unstyled" type="button" class="hs-dropdown-toggle inline-flex justify-center items-center gap-x-2" aria-expanded="false" aria-label="Menu">
                            Actions
                          </button>

                          <div class="hs-dropdown-menu transition-[opacity,margin] duration hs-dropdown-open:opacity-100 opacity-0 w-56 hidden z-10 mt-2 min-w-60 bg-white" role="menu" aria-labelledby="hs-dropdown-unstyled">
                            <a class="block" href="#">Newsletter</a>
                            <a class="block" href="#">Purchases</a>
                            <a class="block" href="#">Downloads</a>
                            <a class="block" href="#">Team Account</a>
                          </div>
                        </div>

Accessibility notes

Keyboard interactions

Command	Description
`Enter`	Activates the selected tab.
`ArrowUp` and `ArrowDown`	Focuses previous/next non-disabled item.
`Home` and `End`	Focuses first/last non-disabled item.
`Esc`	Closes any open Menus.
`A-Z` `a-z`	Focuses first item that matches keyboard input.

JavaScript behavior

Data Options

Parameters	Description	Options	Default value
`data-hs-dropdown-transition`	Data attribute to designate the container to be animated. Should be added to the container (.hs-dropdown).	—	—

Class Options

Parameters	Description	Options	Default value
`[--placement:*]`	Specifies the position of the menu when opened. Should be added to the container (.hs-dropdown).	"auto" \| "auto-start" \| "auto-end" \| "top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right" \| "right" \| "right-start" \| "right-end" \| "left" \| "left-start" \| "left-end"	`bottom`
`[--scope:*]`	Determines whether the dropdown will be moved outside the parent, for correct display in elements with hidden overflow. Requires the `Floating UI` plugin.	"window" \| "parent"	`parent`
`[--auto-close:*]`	Specifies the zone, when clicked, which will close the menu. Should be added to the container (.hs-dropdown).	"inside" \| "outside" \| "false" \| "true"	`true`
`[--has-autofocus:*]`	Disables autofocus on the first focusable element when opening a dropdown. Should be added to the container (.hs-dropdown).	"true" \| "false"	`true`
`[--strategy:*]`	Sets the position to `absolute` instead of `fixed`, and removes the `transform` styles to position the menu `relative` to the relative parent block. Should be added to the container (.hs-dropdown).	"fixed" \| "absolute"	`fixed`
`[--adaptive:*]`	It is used to disable horizontal position calculations (useful for dropdown menus that span the full width of the screen) while still calculating the vertical position. Should be added to the container (.hs-dropdown).	"none" \| "adaptive"	`adaptive`
`[--gpu-acceleration:*]`	Disable/enable position calculation using the transform property. Should be added to the container (.hs-dropdown).	"true" \| "false"	`false`
`[--offset:*]`	Sets the dropdown's bottom or top offset. Should be added to the container (.hs-dropdown).	number	`10`
`[--flip:*]`	Flips the menu's placement when it starts to overlap its reference element. Should be added to the container (.hs-dropdown).	"true" \| "false"	`true`
`[--trigger:*]`	Event to trigger a dropdown. Should be added to the container (.hs-dropdown).	"hover" \| "click" \| "contextmenu"	`click`

Selectors

Name	Description
`hs-dropdown`	Dropdown container.
`hs-dropdown-toggle`	Dropdown toggle.
`hs-dropdown-toggle-wrapper`	A wrapper for a Dropdown toggle, this is useful when some other element is placed in the Dropdown toggle. For example. if you want to place a "+" button inside an existing Dropdown toggle button that opens a modal.
`hs-dropdown-close`	Dropdown close element (can be multiple).

Tailwind Modifiers

Name	Description
`hs-dropdown-open:*`	The modifier that allows you to set tailwind classes when the dropdown menu is open.

Methods

The HSDropdown object is contained within the global window object

Method	Description
Public methods
`open()`	Force open dropdown menu.
`close(isAnimated)`	Force close dropdown menu. `isAnimated` boolean. Indicates whether the dropdown menu is closed with animation
`forceClearState()`	Destroy dropdown.
`destroy()`	Destroys the instance, removes generated markup (if any), removes added classes and attributes.
Static methods
`HSDropdown.getInstance(target)`	Returns the element associated to the `target`. `target` should be a Node or string (valid selector)
`HSDropdown.open(target)`	Open dropdown menu. `target` should be a Node
`HSDropdown.close(target)`	Close dropdown menu. `target` should be a Node

Open item (public method).

                      
                        const dropdown = new HSDropdown(document.querySelector('#dropdown'));
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          dropdown.open();
                        });

Open item (static method).

                      
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          HSDropdown.open('#dropdown');
                        });

Open item (mixed).

                      
                        const { element } = HSDropdown.getInstance('#dropdown', true);
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          element.open();
                        });

Events

Method	Description
`on:open`	Called when any dropdown menu is opened.
`on:close`	Called when any dropdown menu is closed.

Call any function on open example.

                      
                        const el = HSDropdown.getInstance('#dropdown');

                        el.on('open', (instance) => {...});

Demo examples

Looking for prebuilt UI components based on the Tailwind CSS? Preline UI packs hundreds of component examples for all your website needs.

Check out Preline UI Components