The Tailwind Dropdown is a versatile component used to display overlay content on a web page, which can include menus, tabs, and other interactive elements. It's designed for creating a layered navigation experience, allowing users to access various content types without leaving the current page context.
A simple example of a Tailwind Dropdown that is toggled by a button.
Integrate an animated arrow icon to indicate when the dropdown is open.
Divide the dropdown content into sections using a separator element for better organization.
Use Tailwind Width classes to customize the dropdown width.
Apply the .kt-scrollable-y class to the dropdown content element to enable vertical scrolling within it using Tailwind Scrollable component.
Set the data-kt-dropdown-dismiss="true" attribute on an element within the dropdown content to close the dropdown when that element is clicked.
Set the data-kt-dropdown-permanent="true" attribute on a dropdown element to prevent it from being closed.
Use the data-kt-dropdown-placement option to control the opening direction of the Tailwind Dropdown. Explore all available options .
Utilize the data-kt-dropdown-trigger="click" or data-kt-dropdown-trigger="hover" attribute to set the trigger method for dropdowns.
Use data-kt-dropdown-offset="20px, 20px" attribute to specify the offset of the dropdown from the toggle element, adjusting its position on the x and y axes.
Handle advanced dropdown menus.
Display dropdowns inside the Tailwind Modal component.
Display Tailwind Tooltip components in dropdowns.
These data attributes allow you to set options for the dropdown component during auto initialization.
| Option | Type | Default | Description |
|---|---|---|---|
data-kt-dropdown-zindex | Defines the z-index of the dropdown, ensuring it layers correctly above or beneath other page elements. | ||
data-kt-dropdown-hover-timeout | Sets the time in milliseconds before the dropdown is shown or hidden when hovered over. | ||
data-kt-dropdown-trigger | Specifies the trigger action for opening dropdown. | ||
data-kt-dropdown-offset | Specifies the offset of the dropdown from the toggle element, adjusting its position on the x and y axes. | ||
data-kt-dropdown-offset-rtl | Specifies the offset of the dropdown from the toggle element for RTL languages, adjusting its position on the x and y axes. | ||
data-kt-dropdown-permanent | If set to true, keeps the dropdown open indefinitely, overriding the default close behavior. | ||
data-kt-dropdown-placement | Determines the position of the dropdown in relation to the dropdown toggle. | ||
data-kt-dropdown-placement-rtl | Determines the position of the dropdown for RTL languages in relation to the dropdown toggle. |
This table details the custom classes and data attributes used by the dropdown component.
| Name | Description |
|---|---|
| Data Attributes | |
data-kt-dropdown="true" | Automatically initializes Tailwind Dropdown instances on page load. |
data-kt-dropdown-toggle="true" | Marks an element as the trigger for toggling the dropdown menu visibility. |
data-dropdown-content="true" | Indicates the element that contains the content of the dropdown menu, which is displayed when the dropdown is active. |
| Classes | |
open | Added to both the toggle and content elements to indicate the dropdown is active and visible. |
hidden | Sets a specific dropdowns content element to be hidden initially. Can be used to hide the dropdown until it needs to be displayed. |
Custom modifiers to control the dropdown’s style and behavior with Tailwind classes.
| Name | Description |
|---|---|
kt-dropdown-open:* | A custom Tailwind variant activated when the dropdown is shown. It can be applied to the dropdown toggle, dropdown content, and its children, controlling their appearance and behavior in the open state. |
Use KTDropdown component's API methods to programmatically control its behavior.
| Method | Description |
|---|---|
new KTDropdown(element, options) | Creates an object instance of KTDropdown class for the given DOM element and configuration options . |
show() | Shows the subdropdown of the dropdown item associated with itemElement DOM element. |
hide() | Hides the subdropdown of the dropdown item associated with itemElement DOM element. |
toggle() | Toggles the visibility of the subdropdown for the dropdown item associated with itemElement DOM element. |
getToggleElement() | Returns the toggle element that controls the dropdown, allowing direct manipulation or event binding. |
disable() | Disables the dropdown, preventing it from being opened or interacted with. |
enable() | Enables the dropdown, allowing it to be opened and interacted with. |
isOpen() | Returns a boolean indicating whether the dropdown is currently open. |
getOption(name) | Retrieves the value of a configuration option by name parameter from a KTDropdown instance. |
getElement() | Retrieves the DOM element linked to a specific KTDropdown instance. |
on(eventName, handler) | Allows attaching event listeners to the KTDropdown custom events using the eventName and eventId string parameters. These events enable programmatic interaction based on user actions or internal state changes of KTDropdown. The function returns string as a unique identifier for the registered listener, allowing you to remove it later if needed. |
off(eventName, eventId) | Removes an event listener for the eventName and eventId parameters attached with the on method. |
dispose() | Removes the KTDropdown instance from an element, including any associated data stored on the DOM element. |
const dropdownEl = document.querySelector('#my-dropdown');
const dropdown = KTDropdown.getInstance(dropdownEl);
dropdown.show();
dropdown.hide();Manage and interact with KTDropdown instances using these static methods of KTDropdown JavaScript class.
| Method | Description |
|---|---|
init() | Automatically initializes KTDropdown object for all elements with the data-kt-dropdown="true" attribute on page load. |
createInstances() | Allows to create KTDropdown instances for all elements that have been dynamically added to the DOM but haven't been activated yet. |
getInstance(element) | Returns the KTDropdown object associated with the given DOM element element . |
getOrCreateInstance(element) | Returns the existing KTDropdown object for the provided DOM element element , or creates a new instance if none exists, then returns the same. |
// Initialize all dropdowns
KTDropdown.init()
// Initialzie pending dropdowns
KTDropdown.createInstances();
// Get dropdown object
const dropdownEl = document.querySelector('#my-dropdown');
const dropdown = KTDropdown.getInstance(dropdownEl);KTDropdown custom events allows you to register callback functions(event listeners) that will be invoked automatically whenever specific custom events are triggered within the component.
| Event | Description |
|---|---|
show | Triggers before a dropdown is shown. |
shown | Triggers after a dropdown is fully displayed. |
hide | Fires before a dropdown starts the hiding process. |
hidden | Fires after a dropdown is completely hidden. |
const dropdownEl = document.querySelector('#my-dropdown');
const dropdown = KTDropdown.getInstance(dropdownEl);
dropdown.on('show', () => {
console.log('show event');
});
dropdown.on('shown', () => {
console.log('shown event');
});
dropdown.on('hide', (detail) => {
detail.cancel = true;
console.log('hide action canceled');
});