SuperTable Documentation — AZ UI Kit

# Installation

Include the AZ UI Kit bundle in your project. SuperTable is included by default.

HTML

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.tunet.dev/az-ui-kit/1.0.0/az-ui-kit.min.css">

<!-- JavaScript (at end of body) -->
<script src="https://cdn.tunet.dev/az-ui-kit/1.0.0/az-ui-kit.min.js"></script>

Or install via npm:

Terminal

npm install @tunet/az-ui-kit

# Basic Usage

Add data-az-component="super-table" to any table element to activate SuperTable.

HTML

<table data-az-component="super-table">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>John Doe</td>
      <td>john@example.com</td>
      <td>Active</td>
    </tr>
    <!-- More rows... -->
  </tbody>
</table>

Note: SuperTable automatically applies consistent styling, hover states, and responsive behavior. Additional features require their respective data attributes.

# Data Attributes Reference

Complete list of all available data attributes for SuperTable configuration.

Table-Level Attributes

Attribute	Type	Default	Description
data-az-component	string	—	Must be "super-table" to activate
data-az-id	string	auto	Unique identifier for the table instance
data-az-sortable	boolean	false	Enable column sorting globally
data-az-filterable	boolean	false	Enable filtering capabilities
data-az-paginated	boolean	false	Enable pagination
data-az-page-size	number	25	Rows per page
data-az-page-sizes	string	"10,25,50,100"	Available page size options
data-az-bulk-actions	boolean	false	Enable row selection and bulk actions
data-az-export	string	—	Export formats: "csv", "xlsx", "pdf" (comma-separated)
data-az-export-filename	string	"export"	Base filename for exports
data-az-striped	boolean	true	Alternate row background colors
data-az-hover	boolean	true	Row hover highlight
data-az-compact	boolean	false	Reduced padding for dense data
data-az-sticky-header	boolean	false	Keep header visible while scrolling
data-az-resizable	boolean	false	Enable column resizing
data-az-reorderable	boolean	false	Enable column drag-and-drop reordering

Column-Level Attributes (on <th>)

Attribute	Type	Description
data-az-sortable	boolean	Enable sorting for this column
data-az-sort-key	string	Server-side sort field name
data-az-sort-default	"asc" \| "desc"	Default sort direction for this column
data-az-sort-type	string	"string" \| "number" \| "date" \| "custom"
data-az-filterable	boolean	Enable filtering for this column
data-az-filter-type	string	"text" \| "select" \| "date" \| "range" \| "boolean"
data-az-filter-options	string	Comma-separated options for select filters
data-az-width	string	Fixed column width (e.g., "150px", "20%")
data-az-min-width	string	Minimum column width
data-az-hidden	boolean	Hide column (still available in exports)
data-az-sticky	"left" \| "right"	Freeze column to left or right edge

Row-Level Attributes (on <tr>)

Attribute	Type	Description
data-az-row-id	string	Unique row identifier for bulk actions
data-az-row-status	string	"success" \| "warning" \| "error" \| "info"
data-az-expandable	boolean	Enable row expansion for detail view
data-az-expand-url	string	URL to fetch expanded content (HTMX)
data-az-expand-content	string	Selector for inline expand content
data-az-selectable	boolean	Allow row selection (default: true if bulk-actions enabled)
data-az-clickable	boolean	Treat entire row as clickable
data-az-click-url	string	Navigation URL when row clicked

# Sorting

Enable sorting with visual indicators and multi-column support.

Client-Side Sorting

HTML

<table data-az-component="super-table" data-az-sortable="true">
  <thead>
    <tr>
      <th data-az-sortable="true" data-az-sort-type="string">Name</th>
      <th data-az-sortable="true" data-az-sort-type="number">Age</th>
      <th data-az-sortable="true" data-az-sort-type="date" data-az-sort-default="desc">Created</th>
      <th>Actions</th> <!-- Not sortable -->
    </tr>
  </thead>
  <tbody>...</tbody>
</table>

Server-Side Sorting (HTMX)

HTML

<table data-az-component="super-table"
       data-az-sortable="true"
       data-az-sort-mode="server"
       data-az-sort-url="/api/users">
  <thead>
    <tr>
      <th data-az-sortable="true" data-az-sort-key="full_name">Name</th>
      <th data-az-sortable="true" data-az-sort-key="created_at">Created</th>
    </tr>
  </thead>
  <tbody hx-get="/partials/users" hx-trigger="az:sort">...</tbody>
</table>

Multi-Column Sort

Hold Shift and click column headers to add secondary sort criteria.

HTML

<table data-az-component="super-table"
       data-az-sortable="true"
       data-az-multi-sort="true"
       data-az-max-sort-columns="3">
  ...
</table>

# Filtering

Add column filters, global search, and custom filter presets.

Global Search

HTML

<table data-az-component="super-table"
       data-az-filterable="true"
       data-az-search="true"
       data-az-search-placeholder="Search users..."
       data-az-search-columns="name,email">
  ...
</table>

Column Filters

HTML

<th data-az-filterable="true"
    data-az-filter-type="select"
    data-az-filter-options="Active,Pending,Inactive"
    data-az-filter-key="status">
  Status
</th>

<th data-az-filterable="true"
    data-az-filter-type="date"
    data-az-filter-range="true">
  Created
</th>

<th data-az-filterable="true"
    data-az-filter-type="range"
    data-az-filter-min="0"
    data-az-filter-max="1000">
  Amount
</th>

Filter Presets

HTML

<table data-az-component="super-table"
       data-az-filterable="true"
       data-az-filter-presets='[
         {"name": "Active Users", "filters": {"status": "active"}},
         {"name": "This Month", "filters": {"created": "this_month"}},
         {"name": "High Value", "filters": {"amount_gte": 500}}
       ]'>
  ...
</table>

# Pagination

Built-in pagination with customizable page sizes and server-side support.

HTML

<table data-az-component="super-table"
       data-az-paginated="true"
       data-az-page-size="25"
       data-az-page-sizes="10,25,50,100"
       data-az-page-info="true"
       data-az-page-info-format="Showing {start}-{end} of {total}">
  ...
</table>

Server-Side Pagination

HTML

<table data-az-component="super-table"
       data-az-paginated="true"
       data-az-pagination-mode="server"
       data-az-total-count="1250">
  <tbody hx-get="/partials/users"
         hx-trigger="az:paginate"
         hx-include="[data-az-pagination-params]">
    ...
  </tbody>
</table>

# Bulk Actions

Enable row selection and batch operations.

HTML

<table data-az-component="super-table"
       data-az-bulk-actions="true"
       data-az-bulk-select-all="true">
  <thead>
    <tr>
      <th data-az-bulk-checkbox="true"></th>
      <th>Name</th>
      ...
    </tr>
  </thead>
  <tbody>
    <tr data-az-row-id="user-123">
      <td data-az-bulk-checkbox="true"></td>
      <td>John Doe</td>
      ...
    </tr>
  </tbody>
</table>

Bulk Action Toolbar

HTML

<div data-az-bulk-toolbar="users-table" class="hidden">
  <span data-az-selected-count></span> selected
  
  <button data-az-bulk-action="delete"
          data-az-bulk-url="/api/users/bulk-delete"
          data-az-bulk-confirm="Delete selected users?">
    Delete
  </button>
  
  <button data-az-bulk-action="export"
          data-az-bulk-format="csv">
    Export CSV
  </button>
  
  <button data-az-bulk-action="status"
          data-az-bulk-url="/api/users/bulk-status"
          data-az-bulk-payload='{"status": "active"}'>
    Mark Active
  </button>
</div>

# HTMX Integration

SuperTable emits HTMX-compatible events for seamless server-side rendering.

HTML

<table data-az-component="super-table"
       data-az-sortable="true"
       data-az-filterable="true"
       data-az-paginated="true"
       data-az-htmx="true">
  <thead>...</thead>
  
  <tbody id="users-tbody"
         hx-get="/partials/users-table"
         hx-trigger="az:refresh"
         hx-swap="innerHTML"
         hx-indicator="#table-loading">
    <!-- Server-rendered rows -->
  </tbody>
</table>

<div id="table-loading" class="htmx-indicator">
  Loading...
</div>

Server Response Format

Your server should return HTML fragments with the appropriate data attributes:

Python (Django/FastAPI)

@app.get("/partials/users-table")
async def users_table(
    page: int = 1,
    page_size: int = 25,
    sort_by: str = "created_at",
    sort_dir: str = "desc",
    search: str = "",
    status: str = ""
):
    # Query users with parameters...
    users = await get_users(page, page_size, sort_by, sort_dir, search, status)
    total = await count_users(search, status)
    
    # Return HTML partial
    return templates.TemplateResponse(
        "partials/users_rows.html",
        {
            "users": users,
            "total": total,
            "page": page,
            "page_size": page_size
        }
    )

# Events

SuperTable emits custom events you can listen to for advanced integrations.

Event	Description	Detail Properties
az:sort	Column sort changed	{ column, direction, multiSort }
az:filter	Filter applied or changed	{ filters, search }
az:paginate	Page changed	{ page, pageSize }
az:select	Row selection changed	{ selected, rowId }
az:select-all	Select all toggled	{ selected, count }
az:bulk-action	Bulk action triggered	{ action, ids }
az:expand	Row expanded	{ rowId, expanded }
az:export	Export initiated	{ format, scope, data }
az:refresh	Table data needs refresh	{ params }

Listening to Events

JavaScript

document.addEventListener('az:sort', (event) => {
  console.log('Sort changed:', event.detail);
  // { column: 'created_at', direction: 'desc', multiSort: false }
});

document.addEventListener('az:select', (event) => {
  const { selected, rowId } = event.detail;
  console.log(`Row ${rowId} ${selected ? 'selected' : 'deselected'}`);
});

document.addEventListener('az:bulk-action', async (event) => {
  const { action, ids } = event.detail;
  
  if (action === 'custom-action') {
    event.preventDefault(); // Prevent default handling
    await myCustomHandler(ids);
  }
});