ITable ​

Sorting, selection, expansion and per-cell slots. Columns are plain objects, and the rows are yours to supply — in client or server mode.

<script setup lang="ts">
const columns = [
  { key: 'reference', label: 'Reference' },
  { key: 'client', label: 'Client', sortable: true },
  { key: 'status', label: 'Status' },
  { key: 'total', label: 'Total', sortable: true, numeric: true },
]
</script>

<template>
  <ICard padding="none" class="overflow-hidden">
    <ITable :columns="columns" :rows="rows" row-key="id">
      <template #cell-status="{ row }">
        <IBadge :variant="variantFor(row.status)" dot>
          {{ row.status }}
        </IBadge>
      </template>
    </ITable>
  </ICard>
</template>

A #cell-<key> slot replaces the content of that column's cells and receives { row, value }. Everything else falls back to the raw value.

Row actions ​

Fill the row-actions slot and the table adds a trailing column for it, as narrow as its content and pinned to the end. The header is blank, named for screen readers by actionsLabel.

<ITable :columns="columns" :rows="rows" row-key="id">
  <template #row-actions="{ row }">
    <IDropdownMenu :items="actionsFor(row)" align="end">
      <template #trigger>
        <IButton variant="ghost" size="sm" square :aria-label="`Actions for ${row.reference}`">
          <MoreVerticalIcon />
        </IButton>
      </template>
    </IDropdownMenu>
  </template>
</ITable>

Build the entries from the row, so each menu acts on the record beside it:

function actionsFor(invoice) {
  return [
    { label: 'View', icon: ViewIcon, onSelect: () => open(invoice) },
    { label: 'Duplicate', icon: CopyIcon, onSelect: () => duplicate(invoice) },
    '-',
    { label: 'Delete', icon: TrashIcon, danger: true, onSelect: () => remove(invoice) },
  ]
}

A click inside the column never reaches the row, so clickableRows and a menu can coexist. Pair a destructive entry with useConfirm().

Selection ​

Bind v-model:selection to get a checkbox column, with the header checkbox handling the indeterminate state for you. It holds row keys, not row objects.

<ITable
  v-model:selection="selected"
  :columns="columns"
  :rows="rows"
  row-key="id"
  selectable
>
  <template #cell-status="{ row }">
    <IBadge :variant="variantFor(row.status)" dot>
      {{ row.status }}
    </IBadge>
  </template>
</ITable>

Client or server ​

The presence of total decides the mode, and nothing else:

• Absent — client mode. The table sorts and slices the rows it was given.
• Present — server mode. The table renders exactly the rows you pass and emits state changes for you to act on.

In server mode the table tells you when the page or sort changes and renders what you hand back. Fetching, caching and cancellation stay in your data layer.

Server mode ​

Bind v-model:page and v-model:sort, watch them, and pass back the page the server returned along with total. Sort a column or change the page below — each one issues a request, and loading holds the row skeleton while it is in flight.

<script setup lang="ts">
import type { TableSort } from 'iryx-ui'
import { ref, watch } from 'vue'

const rows = ref<Invoice[]>([])
const total = ref(0)
const loading = ref(false)

const page = ref(1)
const sort = ref<TableSort | null>(null)

watch([page, sort], async ([currentPage, currentSort], _old, onCleanup) => {
  const controller = new AbortController()
  onCleanup(() => controller.abort())

  loading.value = true
  try {
    const response = await fetch(
      `/api/invoices?page=${currentPage}&sort=${currentSort?.key ?? ''}&order=${currentSort?.order ?? ''}`,
      { signal: controller.signal },
    )
    const data = await response.json()
    rows.value = data.rows
    total.value = data.total
  }
  finally {
    loading.value = false
  }
}, { immediate: true })
</script>

<template>
  <ITable
    v-model:page="page"
    v-model:sort="sort"
    :columns="columns"
    :rows="rows"
    :total="total"
    :loading="loading"
    row-key="id"
  />
  <IPagination v-model:page="page" :total="total" :items-per-page="10" />
</template>

sort is { key, order } or null, where key is the column's sortKey when it has one and its key otherwise — so a column can display customer.name and sort by customer_name.

onCleanup runs when the inputs change again, which makes it the place to abort the previous request — otherwise a slow first response can land after a fast second one and leave the wrong page on screen.

State ownership ​

Every model is optional. Bind one and you own that piece of state; leave it unbound and the table keeps it internally — so the page, sort and selection can live in a store, in the URL, or nowhere at all:

<ITable
  v-model:page="page"
  v-model:sort="sort"
  v-model:selection="selected"
  :columns="columns"
  :rows="rows"
  :total="total"
/>

Without the markup ​

useDataTable() is the sorting, paging and selection logic on its own, for when you want the behaviour but not the markup:

const table = useDataTable({
  rows: () => rows.value,
  columns: () => columns,
})
// table.pageRows, table.toggleSort, table.headerSelection, …

Props ​

Models: v-model:sort, v-model:page, v-model:perPage, v-model:selection and v-model:expanded.

Column shape ​

interface TableColumn<T = any> {
  /** Accessor path into the row, dot-notation for nested values. Also the slot suffix. */
  key: string
  label?: string
  sortable?: boolean
  /** Sort by a different field than the one displayed. */
  sortKey?: string
  align?: 'start' | 'center' | 'end'
  /** Tabular figures; implies end alignment unless `align` says otherwise. */
  numeric?: boolean
  /** Inline width, e.g. '12rem', or '1px' to shrink to content. */
  width?: string
  /** Extra classes on every cell in the column; a function receives the row. */
  class?: string | ((row: T) => string)
  /** Hide the column outright, or per row (the cell renders empty). */
  hidden?: boolean | ((row: T) => boolean)
}

interface TableSort {
  key: string
  order: 'asc' | 'desc'
}

Events ​

Slots ​