CollapseTable.JS

Why CollapseTable?

• 📱 Keeps important columns visible; folds the rest into an inline details view
• ➕/➖ Per-row toggle (keyboard: Enter / Space)
• ♿ Accessible by default (aria-expanded, aria-controls, role="region", aria-live="polite")
• 🧩 Zero dependencies, tiny footprint
• ⚙️ Production-ready: Resize/Mutation/Intersection observers, hidden-container deferral, stable row IDs, multi-<tbody> support
• 🎛️ Flexible: tableLayout, detailsRender hook, custom icons/strings/classes
• 🧼 Minimal CSS: only scoped utility classes are injected; your design system controls look & feel
• 🧪 Runtime mode: production (default) or development for helpful warnings

Quick Start (CDN)

<script src="https://cdn.jsdelivr.net/npm/@codeseasy/collapsetable@1.2.0/dist/collapsetable.min.js"></script>

<script src="https://cdn.jsdelivr.net/npm/@codeseasy/collapsetable@latest/dist/collapsetable.min.js"></script>

<script>
  var ct = new CollapseTable();
  // Optional during setup: show helpful warnings
  // ct.setMode('development');

  // target can be: "orders" (id without #), "#orders", ".orders-table", "table.responsive", or a <table> element
  ct.set("table-id-here");
</script>

<script src="/path/to/collapsetable.min.js"></script>
<script>
  var ct = new CollapseTable({ /* mode: 'development' */ });
  ct.set("table1");
</script>

Install via npm

npm i @codeseasy/collapsetable

import CollapseTable from '@codeseasy/collapsetable';

const ct = new CollapseTable({ /* mode: 'development' */ });
ct.set('#orders');

const CollapseTable = require('@codeseasy/collapsetable');

const ct = new CollapseTable({ /* mode: 'development' */ });
ct.set('#orders');

Markup requirements

• A <thead> with one header row is required.
• At least one <tbody> is required (multi-<tbody> supported).
• No colspan/rowspan in header or body for responsive collapsing. If spans are detected, collapsing is disabled (base styles still apply and a console warning is emitted).
• The control (+/−) column is automatically inserted as the first column if not present.

Per-column attributes (on <th>)

• data-priority — importance; 1 = never hidden, higher numbers hide earlier
• data-min — width hint in px
• data-label — optional label in the details panel (defaults to header text)

<th data-priority="4" data-min="160" data-label="Placed On">Date</th>

API

const ct = new CollapseTable(globalOptions?);

ct.set(target, perTableOptions?);      // one table
ct.setAll(targets, perTableOptions?);  // many tables
ct.unset(target);                      // remove one
ct.unsetAll(targets);                  // remove many

ct.refresh(target?);    // re-measure & refit (omit to refresh all)
ct.expandAll(target?);  // expand details rows (only if some columns are hidden)
ct.collapseAll(target?);

ct.expandRow(target, rowOrIndex);   // index across all TBODY rows or pass a <tr>
ct.collapseRow(target, rowOrIndex);

ct.on('expand',   ({ table, row }) => {});
ct.on('collapse', ({ table, row }) => {});
ct.on('toggle',   ({ table, row, expanded }) => {});
ct.on('refit',    ({ table, initial, anyHidden }) => {});
ct.on('destroy',  ({ table }) => {}); // unsubscribe: ct.off('expand', handler)

// Set development mode to see helpful warnings during integration:
ct.setMode('development');   // 'production' | 'development' (default: 'production')
ct.getMode();                // => 'development'

// You can also pass at construction or update globally:
const ct2 = new CollapseTable({ mode: 'development' });
ct.updateOptions({ mode: 'production' });

Options (with defaults)

{
  "mode": "production",
  "controlWidth": 46,
  "minWidthDefault": 140,
  "tableLayout": "auto",
  "deferWhenHidden": true,
  "attrs": {
    "priority": "data-priority",
    "min": "data-min",
    "label": "data-label"
  },
  "classNames": {
    "root": "ctbl",
    "control": "ctbl-control",
    "toggle": "ctbl-toggle",
    "details": "ctbl-details",
    "detailsInner": "ctbl-details-inner",
    "detail": "ctbl-detail",
    "name": "ctbl-name",
    "value": "ctbl-value",
    "hide": "ctbl-hide"
  },
  "icons": { "expand": "+", "collapse": "−" },
  "strings": { "toggleTitle": "Show more", "show": "Show details", "hide": "Hide details" },
  "detailsRender": null
}

// Per-table override
ct.set('#invoices', {
  tableLayout: 'fixed',
  icons: { expand: '▶', collapse: '▼' },
  strings: { toggleTitle: 'More', show: 'Show', hide: 'Hide' }
});

// Global helpers
ct.getOptions();                 // clone of current global options (includes mode)
ct.getMode();                    // 'production' | 'development'
ct.setMode('development');       // switch at runtime
ct.updateOptions({ tableLayout: 'fixed' }); // update globals + refresh attached tables
CollapseTable.version; // "1.2.0"

Styling & frameworks

Minimal CSS is injected by the library (scoped under .ctbl) so your design system remains in control. Using Bootstrap? Apply multiple classes to the toggle button via classNames.toggle and widen the control column slightly:

const ct = new CollapseTable();
ct.set('#table-project-list', {
  classNames: {
    root: 'ctbl',
    control: 'ctbl-control',
    toggle: 'ctbl-toggle btn btn-secondary btn-sm'
  },
  controlWidth: 56
});

Tips, limitations & troubleshooting

• Nothing collapses on mobile? Ensure some headers use data-priority="2" or higher. Priority 1 never hides.
• Toggle not visible? The +/− control shows only when at least one non-priority-1 column is hidden. When nothing is hidden, the control column itself is hidden.
• Hidden containers? With deferWhenHidden: true, precise fitting is deferred until visible.
• colspan/rowspan present? Collapsing is disabled; base styles still apply and a console warning is printed.
• Multiple <tbody> sections? Supported. Row indices are 0-based across all data rows in order.
• Development warnings? Only shown in development mode (e.g., too many data-priority="1" columns, invalid/missing priorities). Default mode is production (silent).
• SSR/hydration: initialize on the client after the table exists in the DOM.

CDN links

• Pinned version (1.2.0): jsDelivr – collapsetable.min.js
• Always latest: jsDelivr – collapsetable.min.js

File structure

src/
  CollapseTable.js
  types/
    collapsetable.d.ts
dist/
  collapsetable.min.js
  collapsetable.js
README.md
npm_usage.md
package.json

Types: Provided at src/types/collapsetable.d.ts and published with the package.

License

MIT © 2025 Vishnu (Codes Easy).