@preline/collapse

Collapse

Toggle the visibility of content.

Contents

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

Overview

The Collapse component allows you to show and hide content with smooth transitions. It's a simple, lightweight solution for creating expandable/collapsible sections without the complexity of accordion groups.

Key Features:

• Simple show/hide functionality
• Smooth CSS transitions
• Programmatic control via JavaScript API
• Event system for lifecycle hooks
• Accessibility attributes (ARIA) built-in

Installation

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

npm i @preline/collapse

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/collapse */
@source "../node_modules/@preline/collapse/*.js";
@import "./node_modules/@preline/collapse/variants.css";
@import "./node_modules/@preline/collapse/theme.css";

JavaScript

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

<script src="./node_modules/@preline/collapse/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 HSCollapse from "@preline/collapse/non-auto.mjs";

  new HSCollapse(document.querySelector("#collapse"));
</script>

Via Bundler

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

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

import "@preline/collapse";

@preline/collapse/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 HSCollapse from "@preline/collapse/non-auto";

HSCollapse.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#collapse");
if (el) new HSCollapse(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 collapse component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The content is hidden by default and expands when the button is clicked.

<button type="button" class="hs-collapse-toggle" id="hs-unstyled-collapse" aria-expanded="false" aria-controls="hs-unstyled-collapse-heading" data-hs-collapse="#hs-unstyled-collapse-heading" role="region">
  Collapse
</button>
<div id="hs-unstyled-collapse-heading" class="hs-collapse hidden w-full overflow-hidden transition-[height] duration-300" aria-labelledby="hs-unstyled-collapse">
  This is a collapse body. The content expands and collapses when the toggle button is clicked, with smooth height transitions.
</div>

Structure Requirements:

• hs-collapse-toggle: Required button element that triggers the collapse
• hs-collapse: Required container for collapsible content
• data-hs-collapse: Required attribute on the toggle button, must be a valid CSS selector pointing to the collapse content
• Unique id attributes for the toggle button and collapse content
• Proper ARIA attributes (aria-expanded, aria-controls, aria-labelledby, role="region")

Initial State:

• Set aria-expanded="false" on the toggle button initially
• Add hidden class to the collapse content initially
• Content visibility is controlled by the plugin

Configuration Options

Data Attributes

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

Attribute	Target Element	Type	Default	Description
data-hs-collapse	hs-collapse-toggle (button)	string (CSS selector)	null	Collapse container selector. Must be a valid CSS selector pointing to the hs-collapse element.

Example:

<button data-hs-collapse="#hs-collapse-content">Toggle</button>
<div id="hs-collapse-content" class="hs-collapse hidden">Content</div>

Required CSS Classes

These classes define the structure and must be present for the collapse to function.

Class	Required On	Purpose
hs-collapse	Content container	Identifies the collapsible content area
hs-collapse-toggle	Button element	The clickable element that expands/collapses content

Tailwind Modifiers

Name	Description
hs-collapse-open:*	A modifier that allows you to set Tailwind classes when the collapse is open.

JavaScript API

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

Instance Methods

These methods are called on a collapse instance.

Method	Parameters	Return Type	Description
show()	None	boolean	Opens the collapsed content. Returns false if content is already open, true otherwise.
hide()	None	boolean	Collapses the currently open content. Returns false if content is already closed, true otherwise.
destroy()	None	void	Destroys the collapse instance, removes all generated markup, classes, and event listeners. Use when removing collapse from DOM.

Static Methods

These methods are called directly on the HSCollapse class.

Method	Parameters	Return Type	Description
HSCollapse.getInstance(target, isInstance)	target: HTMLElement | string (CSS selector) isInstance: boolean (optional)	HTMLElement | { id: string | number, element: HSCollapse } | null	Returns the collapse instance or element associated with the target. If isInstance is true, returns collection item object { id, element } where element is the HSCollapse instance. If isInstance is false or omitted, returns the DOM element (HTMLElement). Returns null if collapse instance is not found.
HSCollapse.show(target)	target: HSCollapse | HTMLElement | string (CSS selector)	void	Shows the collapse content identified by target. Accepts a collapse instance, DOM element, or CSS selector string. Static alternative to instance show() method.
HSCollapse.hide(target)	target: HSCollapse | HTMLElement | string (CSS selector)	void	Hides the collapse content identified by target. Accepts a collapse instance, DOM element, or CSS selector string. Static alternative to instance hide() method.

Usage Examples

Example 1: Using instance methods (public API)

// Create a new collapse instance
const collapse = new HSCollapse(document.querySelector('#hs-collapse'));
const showBtn = document.querySelector('#hs-show-btn');

// Show collapse programmatically
showBtn.addEventListener('click', () => {
  collapse.show();
});

Example 2: Using static methods

const showBtn = document.querySelector('#hs-show-btn');

// Show collapse using static method (no instance needed)
showBtn.addEventListener('click', () => {
  HSCollapse.show('#hs-collapse');
});

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

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

if (instance) {
  const { element } = instance; // element is the HSCollapse instance
  const showBtn = document.querySelector('#hs-show-btn');

  // Use instance methods
  showBtn.addEventListener('click', () => {
    element.show();
  });

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

Example 4: Destroying collapse instance

const instance = HSCollapse.getInstance('#hs-collapse', true);

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

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-collapse').remove();
  });
}

Events

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

Event Name	When Fired	Callback Parameter	Description
on:open	After collapse content is opened	HTMLElement (collapse element)	Fires after the collapse content has been displayed. Use for post-open actions like loading content.
on:hide	After collapse content is closed	HTMLElement (collapse element)	Fires after the collapse content has been hidden. Use for cleanup or state updates.

Event Usage Example

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

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

  // Listen to open event
  element.on('open', (collapseElement) => {
    console.log('Collapse opened:', collapseElement);
    // Perform actions after collapse opens
    // e.g., load content, update UI, track analytics
  });

  // Listen to hide event
  element.on('hide', (collapseElement) => {
    console.log('Collapse closed:', collapseElement);
    // Perform cleanup or state updates
  });
}

Common Patterns

Pattern 1: Programmatic Control

Control collapse from external buttons.

<button class="hs-collapse-toggle" data-hs-collapse="#hs-collapse-content">Toggle</button>
<div id="hs-collapse-content" class="hs-collapse hidden">Content</div>

<button id="hs-show-collapse">Show</button>
<button id="hs-hide-collapse">Hide</button>

<script>
  const instance = HSCollapse.getInstance('#hs-collapse-content', true);
  if (instance) {
    const { element } = instance;

    document.querySelector('#hs-show-collapse').addEventListener('click', () => {
      element.show();
    });

    document.querySelector('#hs-hide-collapse').addEventListener('click', () => {
      element.hide();
    });
  }
</script>

License

Copyright (c) 2024 Htmlstream.

Licensed under the MIT License.