Table

Structure

Unlike shadcn's Table/TableHeader/TableBody/TableRow/TableCell family, this is one component, not a set of subcomponents you nest - every semantic element (<table>, <thead>, <tbody>, <tr>, <th>, <td>) is rendered internally from columns/data. You build a table by assembling columns as a plain array, mixing this package's create*Column helpers (utils/table.ts) with plain TableColumn defs for anything with no helper yet:

const columns = [
  createRowSelectColumn<Repo>(),
  createAvatarColumn<Repo>('ownerName', 'Owner', { subtitle: row => row.original.name }),
  createLinkColumn<Repo>('name', createSortableHeader('Repository'), row => row.original.repoUrl),
  createBadgeColumn<Repo>('visibility', 'Visibility', {
    variant: value => value === 'Public' ? 'success' : 'default',
  }),
  createNumericColumn<Repo>('findings', 'Findings'),
  createTruncatedColumn<Repo>('description', 'Description'),
  createSwitchColumn<Repo>('enabled', 'Enabled', (value, row) => { row.original.enabled = value }, { ariaLabel: row => `Enable ${row.original.name}` }),
  createActionsColumn<Repo>(row => [
    { label: 'View', icon: 'i-lucide-eye' },
    { label: 'Remove', icon: 'i-lucide-trash', color: 'error' },
  ]),
]

<Table :data="repos" :columns="columns" />

Order in the array is column order left-to-right - createRowSelectColumn/createAvatarColumn first (selection and identity lead a row), createActionsColumn last (row actions trail it), matching every real table in apps/frontend. Each helper only needs an accessorKey plus a header (string or createSortableHeader(...)); the ones with no data behind them (createRowSelectColumn, createActionsColumn) take no accessorKey at all. See the "Combined columns" example below for this exact table rendered.

Every rendered element is addressed by a ui slot key (also present on the element itself as data-slot) - base (<table>), thead, tbody, tr, th, td, root (the outer wrapper, overflow-x-auto - see Layout below), and separator. This component's own ui prop exposes those eight keys (TableUiSlot); UTable itself also has caption, tfoot, empty, and loading slot keys, not restylable through this component's ui - reach them through the #caption/#empty/#loading slots or a column's own meta.class instead.

• Caption: pass a plain caption string (falls through to UTable directly - this component doesn't declare its own caption prop) or a #caption slot for richer content. UTable renders it visually hidden (sr-only) by default - it's for screen readers identifying the table's content, not a visible title; use a heading above the table for a visible one.
• Footer: give any column in columns a footer property, same as a plain TanStack column def - UTable renders the <tfoot> automatically whenever at least one column defines one. There's no separate footer prop on this component.
• Separator: UTable renders its own <tr data-slot="separator"> between thead and tbody (and again before a <tfoot>), styled by Nuxt UI's own base theme - a second divider stacked on top of thead's own border-b, in a different color token. separator is hidden by default here so thead's border-b is the only line between header and rows; pass your own ui.separator to bring it back for a footer divider.

Layout

• The table is table-fixed w-full - every column shares its width equally from its own <th>, not the natural content-width sizing a plain <table> would give it, and a TanStack column def's size is never read as an inline width here (only pinning offsets use it). Getting a column's width right is one of three explicit choices, not the browser's own auto-layout guess: fill (the default - pass no width option, share whatever's left equally with every other unwidthed column), fixColumnWidth(width, extraClass?) (a static, author-declared width for a small structural/control column that must never grow or shrink - createRowSelectColumn/createActionsColumn both use this to hug a checkbox/kebab button), and hugColumnWidth(accessorKey, headerLabel, options?) (sizes the column to the longest value actually present in the table's current data, in ch units, via meta.style - recomputes whenever data changes, unlike fixColumnWidth's fixed value). createNumericColumn separately uses plain meta.class text-right to right-align without touching width at all.
• Cell text never wraps - UTable's own base theme sets whitespace-nowrap on every td unconditionally, and neither density's own td override touches whitespace-*, so it survives untouched (same single-line-by-default convention as Carbon/Ant Design/Material). That means a long, un-truncated value doesn't grow the row; both th and td also carry overflow-hidden, so it never bleeds into the next column.
• overflow-hidden alone clips at the outer edge of a padded box's padding (flush with the border) - a long value would still visually eat through the full px-4/px-3.5 padding before finally getting clipped, leaving no clean space. NumericCell, Badge, LinkCell, LabeledAvatar's name/subtitle, and TruncatedCell all wrap their actual text in their own zero-padding truncate/min-w-0 inner span instead, so the clip happens at that inner span's own edge - which lines up with the cell's content-box edge, i.e. right where the padding begins, not where it ends. A hand-rolled plain-string cell has no such wrapper and will still eat through its padding on a long value. Use createTruncatedColumn/TruncatedCell for anything that might run long, so it also degrades as an ellipsis-plus-tooltip instead of a bare clip.
• Every <tr> is relative, which is what createRowLinkColumn's full-row overlay hangs off: its link's after:absolute after:inset-0 pseudo-element stretches over the whole row. Anything interactive in another cell of that row must carry relative z-10 to sit above the overlay - createRowSelectColumn's checkbox, createActionsColumn's trigger, createSwitchColumn's switch, createSelectColumn's select, and LinkCell's anchor all do. Display-only cells (TruncatedCell, NumericCell, DateCell, Badge, LabeledAvatar) stay below it, so clicking them still navigates the row.
• The table has a minWidth floor (768px by default) and its outer wrapper (root) is overflow-x-auto - a table with more columns than fit the viewport (or a compact table packed with several narrow columns) scrolls horizontally within itself once its container goes below that width, rather than squeezing every column arbitrarily thin or overflowing the page. Fixed-width columns don't shrink, so on a table whose other columns are fixed the fill (name) column absorbs every lost pixel and can reach zero; pass :min-width="tableMinWidth(fixedWidthPx, fillColumnCount)" (the summed fixed widths, ROW_SELECT_COLUMN_WIDTH_PX/ACTIONS_COLUMN_WIDTH_PX for the control columns, plus the number of unsized columns) so the first fill column keeps 240px and each other one 120px.

Do

• Use density="compact" for a dashboard/admin table where per-row info is short (cost breakdowns, queue jobs); leave it at the default for everything else.
• Use clickable when a row navigates somewhere on click, so the cursor reflects it.
• Pass a real TableColumn<T>[] - column type safety comes from the generic T, don't widen it away with any.

Don't

• Don't reach for ui to change row height or padding as a matter of routine - only for a genuine one-off (e.g. a taller 2-line row). It replaces per slot: each slot string you pass replaces that slot's density default outright (so include every class the slot still needs), while slots you leave out keep their default. A custom ui.tr also drops clickable's cursor-pointer.
• Don't hand-roll the data.length === 0 header-hiding branch - this component already does it.
• Don't use loadingStyle="skeleton" for a background refetch/page change - that would hide data the user was already looking at. Leave loadingStyle at its bar default there.