5.0.0 • Published yesterday

@preline/tabs

Licence

Licensed under MIT and Preline UI Fair Use License

Version

5.0.0

Deps

Size

105 kB

Vulns

Weekly

Stars

6.4K

Summary Dependency Versions

Tabs

Tabs make it easy to switch between different views.

Overview
Installation
Basic usage
Accessibility notes
Configuration Options
JavaScript API
Events
Common Patterns
License

The Tabs component allows users to switch between different content sections within the same context. It supports keyboard navigation, programmatic control, and customizable event types for activation.

Key Features:

Multiple tab panels in a single group
Keyboard navigation support (Arrow keys, Home, End, Enter)
Customizable activation events (click, hover)
Programmatic control via JavaScript API
Event system for tab change tracking
Accessibility attributes (ARIA) built-in

Installation

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

npm i @preline/tabs

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

@import "tailwindcss";

/* @preline/tabs */
@source "../node_modules/@preline/tabs/*.js";
@import "./node_modules/@preline/tabs/variants.css";
@import "./node_modules/@preline/tabs/theme.css";

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag:

<script src="./node_modules/@preline/tabs/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<script type="module">
  import HSTabs from "@preline/tabs/non-auto.mjs";

  new HSTabs(document.querySelector("#tabs"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

@preline/tabs is the auto-init entry: it scans the DOM and initializes matching elements automatically.

import "@preline/tabs";

@preline/tabs/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

import HSTabs from "@preline/tabs/non-auto";

HSTabs.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#tabs");
if (el) new HSTabs(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for a tabs component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The example shows three tabs with corresponding content panels, with the first tab active by default.

<nav class="flex gap-x-2" aria-label="Tabs" role="tablist">
  <button type="button" class="active" id="hs-unstyled-tabs-item-first" aria-selected="true" data-hs-tab="#hs-unstyled-tabs-first" aria-controls="hs-unstyled-tabs-first" role="tab">
    Tab 1
  </button>
  <button type="button" id="hs-unstyled-tabs-item-second" aria-selected="false" data-hs-tab="#hs-unstyled-tabs-second" aria-controls="hs-unstyled-tabs-second" role="tab">
    Tab 2
  </button>
  <button type="button" id="hs-unstyled-tabs-item-third" aria-selected="false" data-hs-tab="#hs-unstyled-tabs-third" aria-controls="hs-unstyled-tabs-third" role="tab">
    Tab 3
  </button>
</nav>

<div class="mt-3">
  <div id="hs-unstyled-tabs-first" role="tabpanel" aria-labelledby="hs-unstyled-tabs-item-first">
    This is the <em>first</em> item's tab body.
  </div>
  <div id="hs-unstyled-tabs-second" class="hidden" role="tabpanel" aria-labelledby="hs-unstyled-tabs-item-second">
    This is the <em>second</em> item's tab body.
  </div>
  <div id="hs-unstyled-tabs-third" class="hidden" role="tabpanel" aria-labelledby="hs-unstyled-tabs-item-third">
    This is the <em>third</em> item's tab body.
  </div>
</div>

Structure Requirements:

role="tablist": Required on the container element (nav, div, etc.)
role="tab": Required on each tab button
role="tabpanel": Required on each content panel
data-hs-tab: Required on each tab button, must be a valid CSS selector pointing to the corresponding tabpanel
Unique id attributes for each tab button and its corresponding panel
Proper ARIA attributes (aria-selected, aria-controls, aria-labelledby)

Initial State:

To have a tab active by default, add the active class to the tab button and set aria-selected="true"
For inactive tabs, add the hidden class to the tabpanel and set aria-selected="false"

Accessibility notes

Keyboard interactions

Command	Description
ArrowLeft / ArrowRight	Selects the previous/next non-disabled tab.
ArrowUp / ArrowDown (in vertical mode)	Selects the previous/next non-disabled tab.
Home / End	Selects the first/last non-disabled tab.
Enter	Activates the selected tab.

Configuration Options

Data Attributes

Data attributes are added directly to HTML elements to configure tab behavior.

Attribute	Target Element	Type	Default	Description
`data-hs-tabs`	Tablist container	object (JSON)	-	Contains configuration options for customizing tab behavior and appearance.
`:eventType`	Inside `data-hs-tabs`	`"click"` \| `"hover"`	`"click"`	Set `hover` to activate tabs on mouseover, or `click` for manual clicks (the default).
`data-hs-tab`	Tab button (trigger)	string (CSS selector)	-	Activate a tab by specifying the selector of the target tabpanel. This must be a valid CSS selector pointing to the tabpanel element.
`data-hs-tab-select`	Tablist container	string (ID)	-	You can pass a select ID there. Each option of this select must have a value equal to the tab ID (e.g., `<option value="#hs-tab-to-select-first">Tab 1</option>`). When you select this value, the corresponding tab will be opened.

Example:

<nav data-hs-tabs='{"eventType": "hover"}' aria-label="Tabs" role="tablist">
  <button data-hs-tab="#hs-tab-first" role="tab">Tab 1</button>
</nav>

Tailwind Modifiers

Name	Description
`hs-tab-active:*`	A modifier that allows you to set Tailwind classes when the tab is active. Can be applied to both the toggle button and the content panel.

JavaScript API

The HSTabs object is available in the global window object after the plugin is loaded.

Instance Methods

These methods are called on a tabs instance.

Method	Parameters	Return Type	Description
`destroy()`	None	`void`	Destroys the tabs instance, removes all generated markup, classes, and event listeners. Use when removing tabs from DOM.

Static Methods

These methods are called directly on the HSTabs class.

Method	Parameters	Return Type	Description
`HSTabs.getInstance(target, isInstance)`	`target`: `HTMLElement \| string` (CSS selector) `isInstance`: `boolean` (optional)	`HSTabs \| { id: string \| number, element: HSTabs } \| null`	Returns the tabs instance associated with the target. If `isInstance` is `true`, returns collection item object `{ id, element }` where `element` is the `HSTabs` instance. If `isInstance` is `false` or omitted, returns the `HSTabs` instance directly. Returns `null` if tabs instance is not found.
`HSTabs.open(target)`	`target`: `HTMLElement`	`void`	Opens the tab identified by target. The target should be a tab button element. Static method to programmatically switch tabs.

Usage Examples

Example 1: Destroying tabs instance

const instance = HSTabs.getInstance('#hs-tabs', true);

if (instance) {
  const { element } = instance;
  const destroyBtn = document.querySelector('#hs-destroy-btn');

  destroyBtn.addEventListener('click', () => {
    element.destroy();
  });
}

Example 2: Opening tab programmatically (static method)

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

openBtn.addEventListener('click', () => {
  const tabButton = document.querySelector('#hs-tab-first');
  
  if (tabButton) {
    HSTabs.open(tabButton);
  }
});

Example 3: Getting instance and using methods (recommended pattern)

// Get the tabs instance
const instance = HSTabs.getInstance('#hs-tabs', true);

if (instance) {
  const { element } = instance;

  // Access instance properties
  console.log('Current tab:', element.current);
  console.log('Current content:', element.currentContent);

  // Clean up when removing from DOM
  function removeTabs() {
    element.destroy();
  }
}

Events

Tabs instances emit events that can be listened to for lifecycle hooks and custom behavior.

Event Name	When Fired	Callback Parameter	Description
`on:change`	When any tab is changed	`{ el: HTMLElement, prev: string, current: string }`	Fires when a tab is switched. Returns an object with: - `el`: The toggle button element that was clicked - `prev`: Previous tab ID - `current`: Current tab ID

Event Usage Example

// Get tabs instance
const instance = HSTabs.getInstance('#hs-tabs', true);

if (instance) {
  const { element } = instance;

  // Listen to change event
  element.on('change', ({ el, prev, current }) => {
    console.log('Tab changed:', {
      clickedButton: el,
      previousTab: prev,
      currentTab: current
    });
    // Perform actions after tab changes
    // e.g., load content, update UI, track analytics
  });
}

Common Patterns

Pattern 1: Hover Activation

Activate tabs on hover instead of click.

<nav data-hs-tabs='{"eventType": "hover"}' aria-label="Tabs" role="tablist">
  <button data-hs-tab="#hs-tab-first" role="tab">Tab 1</button>
  <button data-hs-tab="#hs-tab-second" role="tab">Tab 2</button>
</nav>

Pattern 2: Programmatic Control

Control tabs from external buttons.

<nav id="hs-tabs-first" aria-label="Tabs" role="tablist">
  <button data-hs-tab="#hs-tab-content-first" role="tab">Tab 1</button>
  <button data-hs-tab="#hs-tab-content-second" role="tab">Tab 2</button>
</nav>

<button id="hs-open-tab-first">Open Tab 1</button>
<button id="hs-open-tab-second">Open Tab 2</button>

<script>
  document.querySelector('#hs-open-tab-first').addEventListener('click', () => {
    const tabButton = document.querySelector('[data-hs-tab="#hs-tab-content-first"]');

    if (tabButton) {
      HSTabs.open(tabButton);
    }
  });

  document.querySelector('#hs-open-tab-second').addEventListener('click', () => {
    const tabButton = document.querySelector('[data-hs-tab="#hs-tab-content-second"]');

    if (tabButton) {
      HSTabs.open(tabButton);
    }
  });
</script>

License

Licensed under the MIT License.