Light Dark System

Collapsible

<zn-collapsible> | ZnCollapsible
Since 1.0 experimental

Toggles between showing and hiding content when clicked

Collapsibles provide an interactive way to show and hide content. They’re ideal for accordion-style interfaces, settings panels, and any scenario where you need to progressively disclose information.

This is the collapsible content that can be toggled on and off.

Action Button 
<zn-collapsible caption="Basic Collapsible"
                description="Click to expand and view the content"
                label="Optional Label">
  <p>This is the collapsible content that can be toggled on and off.</p>
  <zn-button>Action Button</zn-button>
</zn-collapsible>

Examples

Basic Usage

A simple collapsible with caption and description. Click anywhere on the header to expand or collapse.

This content is hidden by default and revealed when you click the header.

 
<zn-collapsible caption="Click to expand"
                description="Additional description text">
  <p>This content is hidden by default and revealed when you click the header.</p>
</zn-collapsible>

Expanded State

Use the expanded attribute to show the collapsible in its open state by default.

This content is visible by default because the expanded attribute is set.

Click Me 
<zn-collapsible caption="Already Expanded"
                description="This collapsible starts in the open state"
                expanded>
  <p>This content is visible by default because the expanded attribute is set.</p>
  <zn-button>Click Me</zn-button>
</zn-collapsible>

Default State

Use the default attribute to set the initial state. This is useful when you want to control the default behavior without directly manipulating the expanded property.

This collapsible opens by default using the ‘default’ attribute.

This collapsible starts closed (default behavior).

 
<zn-collapsible caption="Default Open"
                description="Using the default attribute for initial state"
                default="open">
  <p>This collapsible opens by default using the 'default' attribute.</p>
</zn-collapsible>

<br />

<zn-collapsible caption="Default Closed"
                description="This is the default behavior"
                default="closed">
  <p>This collapsible starts closed (default behavior).</p>
</zn-collapsible>

With Label

Use the label attribute to add a label on the right side of the header.

Labels are useful for displaying version numbers, status, or other metadata.

 
<zn-collapsible caption="Section Title"
                description="Optional description"
                label="v2.0">
  <p>Labels are useful for displaying version numbers, status, or other metadata.</p>
</zn-collapsible>

Item Counter

Use the show-number attribute to display a count of items within the collapsible. The count appears as a chip when the collapsible is closed.

Alice Johnson
Bob Smith
Carol Williams
David Brown
 
<zn-collapsible caption="Team Members"
                description="View all team members"
                show-number>
  <div>Alice Johnson</div>
  <div>Bob Smith</div>
  <div>Carol Williams</div>
  <div>David Brown</div>
</zn-collapsible>

Custom Element Counter

Use the count-element attribute to count specific elements instead of all children. This is useful when you have complex content structures.

User 1 User 2 User 3

Additional content that won’t be counted

 
<zn-collapsible caption="Active Users"
                description="Users currently online"
                show-number
                count-element="zn-chip">
  <div>
    <zn-chip>User 1</zn-chip>
    <zn-chip>User 2</zn-chip>
    <zn-chip>User 3</zn-chip>
  </div>
  <p>Additional content that won't be counted</p>
</zn-collapsible>

Flush Content

Use the flush attribute to remove the left padding/margin from the content area, making it align with the edges.

This button aligns with the left edge

Content starts at the container edge

 
<zn-collapsible caption="Flush Content"
                description="No left padding on content"
                flush>
  <zn-button>This button aligns with the left edge</zn-button>
  <p>Content starts at the container edge</p>
</zn-collapsible>

Custom Header Slot

Use the header slot to completely customize the header appearance and behavior.

Custom Header Design

When you provide a custom header, you have full control over its appearance.

 
<zn-collapsible>
  <div slot="header" style="padding: 1rem; background: var(--zn-color-primary-50); display: flex; justify-content: space-between; align-items: center;">
    <strong>Custom Header Design</strong>
    <zn-icon src="expand_more" class="expand"></zn-icon>
  </div>
  <p>When you provide a custom header, you have full control over its appearance.</p>
</zn-collapsible>

Custom Caption Slot

Use the caption slot to add custom content to the caption area, such as icons, badges, or toggles.

Settings Section New

The caption slot allows you to add custom elements to the title area.

 
<zn-collapsible>
  <div slot="caption" style="display: flex; align-items: center; gap: 0.5rem;">
    <zn-icon src="settings"></zn-icon>
    <span>Settings Section</span>
    <zn-chip size="small" type="info">New</zn-chip>
  </div>
  <p>The caption slot allows you to add custom elements to the title area.</p>
</zn-collapsible>

With Toggle Controls

Integrate toggles into the caption slot to create settings panels. The collapsible automatically detects toggles and adjusts the UI accordingly.

Email Notifications
Marketing emails
Product updates
Security alerts 
<zn-collapsible caption="Notification Settings">
  <div class="flex-mid" slot="caption">
    <div class="grow zn-pr">Email Notifications</div>
    <zn-toggle name="email-enabled"></zn-toggle>
  </div>
  <div style="padding: 1rem;">
    <zn-toggle name="marketing" size="medium">Marketing emails</zn-toggle>
    <br />
    <zn-toggle name="updates" size="medium" checked>Product updates</zn-toggle>
    <br />
    <zn-toggle name="alerts" size="medium" checked>Security alerts</zn-toggle>
  </div>
</zn-collapsible>

Permission Panel Example

A practical example showing how to build a permission management interface.

Billing Permissions
View Invoices
Can view all billing invoices
Manage Payment Methods
Can add or remove payment methods
Process Refunds
Can issue refunds to customers 
<zn-collapsible>
  <div class="flex-mid" slot="caption">
    <div class="grow zn-pr">Billing Permissions</div>
    <zn-toggle name="billing-enabled" checked></zn-toggle>
  </div>

  <div style="display: flex; flex-direction: column; gap: 0.5rem;">
    <div style="display: flex; justify-content: space-between; align-items: center; padding: 1rem; border-bottom: 1px solid var(--zn-color-neutral-200);">
      <div>
        <strong>View Invoices</strong>
        <div style="font-size: 0.875rem; color: var(--zn-color-neutral-600);">
          Can view all billing invoices
        </div>
      </div>
      <zn-toggle name="view-invoices" size="medium" checked></zn-toggle>
    </div>

    <div style="display: flex; justify-content: space-between; align-items: center; padding: 1rem; border-bottom: 1px solid var(--zn-color-neutral-200);">
      <div>
        <strong>Manage Payment Methods</strong>
        <div style="font-size: 0.875rem; color: var(--zn-color-neutral-600);">
          Can add or remove payment methods
        </div>
      </div>
      <zn-toggle name="manage-payments" size="medium"></zn-toggle>
    </div>

    <div style="display: flex; justify-content: space-between; align-items: center; padding: 1rem;">
      <div>
        <strong>Process Refunds</strong>
        <div style="font-size: 0.875rem; color: var(--zn-color-neutral-600);">
          Can issue refunds to customers
        </div>
      </div>
      <zn-toggle name="process-refunds" size="medium"></zn-toggle>
    </div>
  </div>
</zn-collapsible>

State Persistence with Session Storage

The collapsible can remember its state across page loads using session or local storage with the store-key attribute.

This collapsible’s state will persist during your browser session.

Try expanding or collapsing it, then refresh the page.

 
<zn-collapsible caption="Preferences"
                description="State saved in session storage"
                store-key="user-preferences">
  <p>This collapsible's state will persist during your browser session.</p>
  <p>Try expanding or collapsing it, then refresh the page.</p>
</zn-collapsible>

State Persistence with Local Storage

Use the local-storage attribute to persist state permanently across browser sessions.

This collapsible’s state persists even after closing the browser.

The state is stored in localStorage instead of sessionStorage.

 
<zn-collapsible caption="Advanced Settings"
                description="State saved permanently"
                store-key="advanced-settings"
                local-storage>
  <p>This collapsible's state persists even after closing the browser.</p>
  <p>The state is stored in localStorage instead of sessionStorage.</p>
</zn-collapsible>

Storage with TTL

Use the store-ttl attribute to set a time-to-live (in seconds) for the stored state.

This collapsible’s state will be remembered for 60 seconds.

After that, it will revert to the default closed state.

 
<zn-collapsible caption="Temporary State"
                description="State expires after 60 seconds"
                store-key="temporary-state"
                store-ttl="60">
  <p>This collapsible's state will be remembered for 60 seconds.</p>
  <p>After that, it will revert to the default closed state.</p>
</zn-collapsible>

Accordion Pattern

Create an accordion by grouping multiple collapsibles together.

Content for section 1.

Content for section 2.

Content for section 3.

 
<div style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
  <zn-collapsible caption="Section 1"
                  description="First section details"
                  default="open">
    <p>Content for section 1.</p>
  </zn-collapsible>

  <zn-collapsible caption="Section 2"
                  description="Second section details">
    <p>Content for section 2.</p>
  </zn-collapsible>

  <zn-collapsible caption="Section 3"
                  description="Third section details">
    <p>Content for section 3.</p>
  </zn-collapsible>
</div>

Nested Collapsibles

Collapsibles can be nested to create hierarchical content structures.

This is the parent content.

Nested collapsible content 1

Nested collapsible content 2

 
<zn-collapsible caption="Parent Section" expanded>
  <p>This is the parent content.</p>

  <zn-collapsible caption="Child Section 1" flush>
    <p>Nested collapsible content 1</p>
  </zn-collapsible>

  <zn-collapsible caption="Child Section 2" flush>
    <p>Nested collapsible content 2</p>
  </zn-collapsible>
</zn-collapsible>

Programmatic Control

You can control the collapsible programmatically by setting the expanded property.

This collapsible can be controlled programmatically.
Expand Collapse Toggle 
<zn-collapsible id="programmatic-collapsible"
                caption="Programmatic Control"
                description="Control via JavaScript">
  <p>This collapsible can be controlled programmatically.</p>
</zn-collapsible>

<br />

<zn-button id="expand-btn">Expand</zn-button>
<zn-button id="collapse-btn" color="secondary">Collapse</zn-button>
<zn-button id="toggle-btn" color="info">Toggle</zn-button>

<script type="module">
  const collapsible = document.getElementById('programmatic-collapsible');

  document.getElementById('expand-btn').addEventListener('click', () => {
    collapsible.expanded = true;
  });

  document.getElementById('collapse-btn').addEventListener('click', () => {
    collapsible.expanded = false;
  });

  document.getElementById('toggle-btn').addEventListener('click', () => {
    collapsible.expanded = !collapsible.expanded;
  });
</script>

State Change Detection

Monitor the collapsible’s state changes using property observation or mutation observers.

Click the header to expand or collapse.
State: Collapsed 
<zn-collapsible id="state-monitor"
                caption="State Monitor"
                description="Watch for state changes">
  <p>Click the header to expand or collapse.</p>
</zn-collapsible>

<div id="state-output" style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-100); border-radius: 4px;">
  <strong>State:</strong> <span id="state-text">Collapsed</span>
</div>

<script type="module">
  const collapsible = document.getElementById('state-monitor');
  const stateText = document.getElementById('state-text');

  // Use a MutationObserver to watch for attribute changes
  const observer = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      if (mutation.type === 'attributes' && mutation.attributeName === 'expanded') {
        const isExpanded = collapsible.hasAttribute('expanded');
        stateText.textContent = isExpanded ? 'Expanded' : 'Collapsed';
        stateText.style.color = isExpanded ? 'var(--zn-color-success)' : 'var(--zn-color-neutral-600)';
      }
    });
  });

  observer.observe(collapsible, { attributes: true });
</script>

Methods

The collapsible provides a public method for recalculating item counts:

  • recalculateNumberOfItems() - Recalculates the number of items when using show-number. Useful when content is dynamically updated.
Item 1
Add Item 
<zn-collapsible id="dynamic-collapsible"
                caption="Dynamic Items"
                description="Items can be added dynamically"
                show-number>
  <div id="item-container">
    <div>Item 1</div>
  </div>
</zn-collapsible>

<br />

<zn-button id="add-item-btn">Add Item</zn-button>

<script type="module">
  const collapsible = document.getElementById('dynamic-collapsible');
  const container = document.getElementById('item-container');
  let itemCount = 1;

  document.getElementById('add-item-btn').addEventListener('click', () => {
    itemCount++;
    const newItem = document.createElement('div');
    newItem.textContent = `Item ${itemCount}`;
    container.appendChild(newItem);

    // Manually trigger recalculation
    collapsible.recalculateNumberOfItems();
  });
</script>

Complete Example

A comprehensive example demonstrating multiple features together.

Privacy Settings

Make profile public Show email address Show phone number

Notification Preferences

Email notifications SMS notifications Push notifications
Save Changes 
<div style="max-width: 600px;">
  <zn-collapsible
    caption="User Profile Settings"
    description="Manage your profile preferences"
    label="Required"
    show-number
    count-element="zn-toggle"
    store-key="profile-settings"
    local-storage>

    <div style="display: flex; flex-direction: column; gap: 1rem; padding: 1rem;">
      <div>
        <h4 style="margin: 0 0 0.5rem 0;">Privacy Settings</h4>
        <zn-toggle name="profile-public" checked>Make profile public</zn-toggle>
        <zn-toggle name="show-email">Show email address</zn-toggle>
        <zn-toggle name="show-phone">Show phone number</zn-toggle>
      </div>

      <div>
        <h4 style="margin: 0 0 0.5rem 0;">Notification Preferences</h4>
        <zn-toggle name="email-notifications" checked>Email notifications</zn-toggle>
        <zn-toggle name="sms-notifications">SMS notifications</zn-toggle>
        <zn-toggle name="push-notifications" checked>Push notifications</zn-toggle>
      </div>

      <zn-button color="primary">Save Changes</zn-button>
    </div>
  </zn-collapsible>
</div>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.86/dist/components/collapsible/collapsible.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.86/dist/components/collapsible/collapsible.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/collapsible/collapsible.js';

Slots

Name Description
header Clicking will toggle the show state of the data

Learn more about using slots.

Dependencies

This component automatically imports the following dependencies.

  • <zn-example>
  • <zn-icon>