# Tailwind Plus Elements Documentation Tailwind Plus Elements is a JavaScript UI component library that powers all the interactive behavior in our HTML snippets. It has no dependencies on JavaScript frameworks like React, and works with any modern stack—Next.js, Rails, Laravel, Svelte, Astro, or even plain HTML. ## Available components Tailwind Plus Elements includes the following UI components: - [Autocomplete](#autocomplete) - [Command palette](#command-palette) - [Dialog](#dialog) - [Disclosure](#disclosure) - [Dropdown menu](#dropdown-menu) - [Popover](#popover) - [Select](#select) - [Tabs](#tabs) ## Browser support Elements targets the same modern browsers supported by Tailwind CSS v4.0, and relies on the following minimum versions: - **Chrome 111** _(released March 2023)_ - **Safari 16.4** _(released March 2023)_ - **Firefox 128** _(released July 2024)_ ## Installing in your project The easiest way to install Elements is via the CDN. To do this, add the following script to your project's `` tag: ```html ``` Alternatively, if you have a build pipeline you can also install it via npm: ```bash npm install @tailwindplus/elements ``` Next, import Elements into your root layout: ```js import '@tailwindplus/elements' ``` ## Detecting when ready Sometimes you may want to add additional functionality to the Elements' components using JavaScript. To do this you must ensure that Elements has been loaded and is ready before interacting with it. You can do this by listening to the `elements:ready` event on the `window` object: ```js function myFunction() { let autocomplete = document.getElementById('autocomplete') // Do something with the autocomplete element } if (customElements.get('el-autocomplete')) { myFunction() } else { window.addEventListener('elements:ready', myFunction) } ``` ## Autocomplete The `` component is a text input that allows users to enter arbitrary values or select from a list of filtered suggestions. It behaves like a native``, but offers greater control over styling. ### Component API #### `` The main autocomplete component that manages form integration, filtering, and coordinates with its child components | Type | Name | Description | | ------------------------- | -------------- | ----------------------------------------- | | CSS variables (Read-only) | --input-width | Provides the width of the input element. | | CSS variables (Read-only) | --button-width | Provides the width of the button element. | #### `` The options container that handles the popover behavior. | Type | Name | Description | | --------------------------- | --------------- | ------------------------------------------------------------------------------------------ | | Attributes | popover | Required to enable the popover behavior. | | Attributes | anchor | Configures the way the options are anchored to the button. | | Attributes | anchor-strategy | Sets the `position` CSS property of the popover to either `absolute` (default) or `fixed`. | | CSS variables | --anchor-gap | Sets the gap between the anchor and the popover. | | CSS variables | --anchor-offset | Sets the distance that the popover should be nudged from its original position. | | Data attributes (Read-only) | data-closed | Present before transitioning in, and when transitioning out. | | Data attributes (Read-only) | data-enter | Present when transitioning in. | | Data attributes (Read-only) | data-leave | Present when transitioning out. | | Data attributes (Read-only) | data-transition | Present when transitioning in or out. | | Methods | togglePopover() | Toggles the options visibility. | | Methods | showPopover() | Shows the options. | | Methods | hidePopover() | Hides the options. | #### `` Individual selectable option within the autocomplete. | Type | Name | Description | | --------------------------- | ------------- | ------------------------------------------------- | | Attributes | value | The value of the option (required for selection). | | Attributes | disabled | Whether the option is disabled. | | ARIA attributes (Read-only) | aria-selected | Present when the option is selected. | #### `` Automatically displays the content of the currently selected option. ### Examples #### Basic example Use the `` and `` components, along with a native `` and ` Wade Cooper Tom Cooper Jane Doe ``` #### Positioning the dropdown Add the `anchor` prop to the `` to automatically position the dropdown relative to the ``: ```html ``` Use the values `top`, `right`, `bottom`, or `left` to center the dropdown along the appropriate edge, or combine it with `start` or `end` to align the dropdown to a specific corner, such as `top start` or `bottom end`. To control the gap between the input and the dropdown, use the `--anchor-gap` CSS variable: ```html ``` Additionally, you can use `--anchor-offset` to control the distance that the dropdown should be nudged from its original position. #### Setting the dropdown width The `` has no width set by default, but you can add one using CSS: ```html ``` If you'd like the dropdown width to match the `` width, use the `--input-width` CSS variable that's exposed on the `` element: ```html ``` #### Adding transitions To animate the opening and closing of the dropdown, target the `data-closed`, `data-enter`, `data-leave`, and `data-transition` attributes with CSS to style the different stages of the transition: ```html ``` #### Disabling the input To disable the input, add the `disabled` attribute to the ``: ```html ``` ## Command palette The `` component provides a fast, keyboard-friendly way for users to search and select from a predefined list of options. It's typically displayed inside a dialog — often triggered with a `Cmd+K` shortcut — making it ideal for building power-user features like global searches. ### Component API #### `` The main command component that manages filtering and coordinates with its child components | Type | Name | Description | | ---------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Attributes | name | The form field name for the command when used in forms. | | Attributes | value | The selected value of the command. Can be read and set programmatically. | | Events | change | Dispatched when the active item changes. Detail contains `relatedTarget` property with the active item or `null`. | | Methods | setFilterCallback(cb) | Allows you to customize the filtering behavior of the command. The callback receives an object with `query`, `node` and `content` properties, and should return a `boolean`. | | Methods | reset() | Resets the command to its initial state. | #### `` Contains all the command items and groups. All focusable children will be considered options. #### `` Optional container for suggestion items that are shown when the input is empty. #### `` Groups related command items together. #### `` Optional element shown when no items match the current query. #### `` Optional preview content shown when a specific item is active. | Type | Name | Description | | ---------- | ---- | ------------------------------------------------------------- | | Attributes | for | The `id` of the item this preview content is associated with. | ### Examples #### Basic example Use the ``, ``, `` components, along with a native ``, to build a command palette: ```html ``` ## Dialog The `` component is a lightweight wrapper around the native `` element that adds scroll locking, click-outside-to-close support, and smooth exit transitions that work consistently across all browsers. It builds on standard HTML APIs while making dialogs easier to use and style. ### Component API #### `` Wrapper around the native `` element used to manage the open state and transitions. | Type | Name | Description | | --------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Attributes | open | A boolean attribute that indicates whether the dialog is open or closed. You can change the attribute to dynamically open or close the dialog. | | Data attributes (Read-only) | data-closed | Present before transitioning in, and when transitioning out. | | Data attributes (Read-only) | data-enter | Present when transitioning in. | | Data attributes (Read-only) | data-leave | Present when transitioning out. | | Data attributes (Read-only) | data-transition | Present when transitioning in or out. | | Events | open | Dispatched when the dialog is opened in any way other than by updating the `open` attribute. | | Events | close | Dispatched when the dialog is closed in any way other than by updating the `open` attribute. | | Events | cancel | Dispatched when the user attempts to dismiss the dialog via Escape key or clicking outside. Calling `preventDefault()` prevents the dialog from closing. | | Methods | show() | Shows the dialog in modal mode. | | Methods | hide() | Hides the dialog. Takes an optional object with a `restoreFocus` property to disable the default focus restoration. | #### `` The native dialog element. | Type | Name | Description | | -------- | ---------- | ------------------ | | Commands | show-modal | Opens the dialog. | | Commands | close | Closes the dialog. | #### `` The visual backdrop behind your dialog panel. | Type | Name | Description | | --------------------------- | --------------- | ------------------------------------------------------------ | | Data attributes (Read-only) | data-closed | Present before transitioning in, and when transitioning out. | | Data attributes (Read-only) | data-enter | Present when transitioning in. | | Data attributes (Read-only) | data-leave | Present when transitioning out. | | Data attributes (Read-only) | data-transition | Present when transitioning in or out. | #### `` The main content area of your dialog. Clicking outside of this will trigger the dialog to close. | Type | Name | Description | | --------------------------- | --------------- | ------------------------------------------------------------ | | Data attributes (Read-only) | data-closed | Present before transitioning in, and when transitioning out. | | Data attributes (Read-only) | data-enter | Present when transitioning in. | | Data attributes (Read-only) | data-leave | Present when transitioning out. | | Data attributes (Read-only) | data-transition | Present when transitioning in or out. | ### Examples #### Basic example Use the `` and `` components, along with a native ``, to build a dialog: ```html

Delete profile

Are you sure? This action is permanent and cannot be undone.

 ``` #### Opening the dialog You can open dialogs using the `show-modal` [invoker command](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API): ```html ``` Alternatively you can add the `open` attribute to the `` to open it: ```diff - + ``` You can also programmatically open the dialog using the `show()` method on ``: ```html ``` #### Closing the dialog You can close dialogs using the `close` [invoker command](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API): ```html ``` Alternatively you can remove the `open` attribute from the `` to close it: ```diff - + ``` You can also programmatically close the dialog using the `hide()` method on ``: ```html ``` #### Adding a backdrop Use the `` component to add a backdrop behind your dialog panel: ```html ``` The primary benefit of using the `` component over the native `::backdrop` pseudo-element is that it can be transitioned reliably using CSS. #### Adding transitions To animate the opening and closing of the dialog, target the `data-closed`, `data-enter`, `data-leave`, and `data-transition` attributes with CSS to style the different stages of the transition: ```html ``` ## Disclosure The `` component provides a simple, accessible way to show and hide content — ideal for building things like toggleable accordion panels or expandable sections. ### Component API #### `` Contains the content of the disclosure. | Type | Name | Description | | --------------------------- | --------------- | ------------------------------------------------------------ | | Attributes | hidden | Whether the disclosure is initially hidden (closed). | | Attributes | open | Automatically synced with the `hidden` attribute. | | Data attributes (Read-only) | data-closed | Present before transitioning in, and when transitioning out. | | Data attributes (Read-only) | data-enter | Present when transitioning in. | | Data attributes (Read-only) | data-leave | Present when transitioning out. | | Data attributes (Read-only) | data-transition | Present when transitioning in or out. | | Methods | show() | Shows the disclosure. | | Methods | hide() | Hides the disclosure. | | Methods | toggle() | Toggles the disclosure. | | Commands | --show | Shows the disclosure. | | Commands | --hide | Hides the disclosure. | | Commands | --toggle | Toggles the disclosure. | ### Examples #### Basic example Use the `` component, along with a native ` ``` #### Opening a disclosure You can open disclosures using the `--show` [invoker command](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API): ```html ``` Alternatively you can remove the `hidden` attribute to open it: ```diff -