Table

# Brok UI: Table (`table`)

A responsive data table with header, body, row, cell, sort-button, and shared announced loading and empty-state row parts; rows can link as a whole.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add table
```

## Usage

```blade
<x-ui.table class="w-full max-w-lg text-start">
    <x-ui.table.header>
        <x-ui.table.row>
            <x-ui.table.head>{{ __('Name') }}</x-ui.table.head>
            <x-ui.table.head>{{ __('Email') }}</x-ui.table.head>
            <x-ui.table.head>{{ __('Role') }}</x-ui.table.head>
        </x-ui.table.row>
    </x-ui.table.header>
    <x-ui.table.body>
        <x-ui.table.row>
            <x-ui.table.cell>{{ __('Jane Doe') }}</x-ui.table.cell>
            <x-ui.table.cell>[email protected]</x-ui.table.cell>
            <x-ui.table.cell>{{ __('Admin') }}</x-ui.table.cell>
        </x-ui.table.row>
        <x-ui.table.row>
            <x-ui.table.cell>{{ __('Alex Brown') }}</x-ui.table.cell>
            <x-ui.table.cell>[email protected]</x-ui.table.cell>
            <x-ui.table.cell>{{ __('Member') }}</x-ui.table.cell>
        </x-ui.table.row>
    </x-ui.table.body>
</x-ui.table>
```

## Props

- `variant` (default|striped|borderless|vertical-lines, default `default`) — Semantic row and border treatment.
- `density` (string, default `default`) — Declared by @props in the shipped Blade source.
- `sticky` (bool, default `false`) — Declared by @props in the shipped Blade source.
- `bordered` (bool, default `false`) — Declared by @props in the shipped Blade source.
- `align` (start|center|end, default `start`) — Documented catalog control used by the preview workbench.
- `href` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `nowrap` (bool, default `false`) — Declared by @props in the registry Blade source.
- `direction` (string, default `none`) — Declared by @props in the registry Blade source.
- `state` (string, default `empty`) — Declared by @props in the registry Blade source.
- `colspan` (int, default `1`) — Declared by @props in the registry Blade source.
- `heading` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `description` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use when users need exact comparison across rows and columns, plus sorting or filtering.
- Presenting tabular data in rows and columns with the base table primitives: table, table.header, table.row, table.cell, and related parts.
- Choosing a presentational variant, such as striped rows or column dividers, without adding sorting, filtering, or pagination.

## Avoid when

- Do not use a table for narrative browsing or small mobile contexts where cards or lists are easier to scan.
- Prefer when exact cross-item comparison is the core job, not merely browsing.
- Rows need client-side sorting, filtering, or selection; use data-table. Rows are paginated server-side with Livewire; use livewire-data-table.

## Anti-patterns

- Using cards when exact comparison is primary
- Forcing wide tables into narrow layouts without adaptation

## Rules

- Use the `<brok:table>` tag (or `<x-ui.table>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/table
- Registry JSON (files, props, contract): https://brokui.dev/r/open/table.json

@props([
    // Presentational variant. Interactive features (sorting, filtering,
    // pagination, selection, …) live in the richer `data-table` component.
    //   default        — bordered rows (existing look)
    //   striped        — zebra-striped body rows
    //   borderless     — no row dividers ("without dividers")
    //   vertical-lines — column dividers as well as row dividers
    'variant' => 'default',
    // Row padding scale: 'default' or 'dense' (compact).
    'density' => 'default',
    // Sticky header: keeps <thead> visible while the wrapper scrolls vertically.
    // When true, set a height on the table via class (e.g. max-h-80) for it to bite.
    'sticky' => false,
    // A hairline around the whole table (the wrapper), rounded to the control tier.
    'bordered' => false,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $table = $styles['table'] ?? [];

    $variant = array_key_exists($variant, $table['variants'] ?? []) ? $variant : 'default';
    $density = array_key_exists($density, $table['density'] ?? []) ? $density : 'default';

    $tableClass = trim(implode(' ', array_filter([
        $table['base'] ?? 'w-full caption-bottom text-sm',
        $table['variants'][$variant] ?? '',
        $table['density'][$density] ?? '',
        $sticky ? ($table['sticky'] ?? '') : '',
        $bordered ? '[&_tbody_tr:last-child]:border-b-0' : '',
    ])));
@endphp

<div
    data-slot="table-wrapper"
    @class([
        'relative w-full max-w-full overflow-x-auto overscroll-x-contain',
        'overflow-y-auto' => $sticky,
        'rounded-md border border-border' => $bordered,
    ])
    @if ($bordered) data-bordered="true" @endif
>
    <table
        data-slot="table"
        data-variant="{{ $variant }}"
        data-density="{{ $density }}"
        @if ($sticky) data-sticky="true" @endif
        {{ $attributes->merge(['class' => $tableClass]) }}
    >
        {{ $slot }}
    </table>
</div>

@props([
    // Makes the whole row a pointer target for this URL (Fitts). The row keeps
    // one real link for keyboard and screen readers: put an <a> with the same
    // href (or `data-row-link`) in the primary cell. Clicks elsewhere on the
    // row forward to that link; buttons, inputs and menus in other cells keep
    // working. Null keeps a plain row.
    'href' => null,
])

@php
    $href = filled($href) ? (string) $href : null;
@endphp

<tr
    data-slot="table-row"
    @if ($href)
        data-href="{{ $href }}"
        x-data="uiTableRow({ href: @js($href) })"
        x-on:click="open($event)"
        x-on:auxclick="open($event)"
    @endif
    {{ $attributes->merge(['class' => 'border-b border-border transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted'.($href ? ' cursor-pointer focus-within:bg-muted/50 motion-reduce:transition-none' : '')]) }}
>
    {{ $slot }}
</tr>

@props([
    // Text alignment for the header cell. Numeric and action columns need
    // `end` (or `center`) without relying on a consumer-supplied Tailwind
    // class to out-order the `text-start` this recipe used to bake in
    // unconditionally — generated stylesheet order is not a tie-break
    // guarantee (see CLAUDE.md "Consumer classes are appended through
    // Laravel's attribute bag"). `start` reproduces the previous
    // hardcoded output exactly.
    'align' => 'start',
    // Keep the header label on one line — useful next to a sort button or a
    // narrow numeric column where wrapping would misalign the column.
    'nowrap' => false,
])

@php
    $alignClasses = [
        'start' => 'text-start',
        'center' => 'text-center',
        'end' => 'text-end',
    ];
    $alignClass = $alignClasses[$align] ?? $alignClasses['start'];
@endphp

<th
    data-slot="table-head"
    data-align="{{ $align }}"
    {{ $attributes->merge([
        'class' => trim(
            'h-10 px-3 '.$alignClass.' align-middle text-xs font-medium text-muted-foreground [&:has([role=checkbox])]:w-px'
            .($nowrap ? ' whitespace-nowrap' : '')
        ),
    ]) }}
>
    {{ $slot }}
</th>

@props([
    'direction' => 'none',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $table = $styles['table'];
    $resolvedDirection = in_array($direction, ['none', 'ascending', 'descending'], true) ? $direction : 'none';
@endphp

<button
    type="button"
    data-slot="table-sort-button"
    data-direction="{{ $resolvedDirection }}"
    {{ $attributes->merge(['class' => $table['sortButton']]) }}
>
    <span class="min-w-0 truncate">{{ $slot }}</span>
    <span class="shrink-0 text-muted-foreground/70 group-hover/sort:text-foreground" aria-hidden="true">
        <svg class="size-4 group-data-[direction=ascending]/sort:hidden group-data-[direction=descending]/sort:hidden" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="m7 15 5 5 5-5" />
            <path d="m7 9 5-5 5 5" />
        </svg>
        <svg class="hidden size-4 group-data-[direction=ascending]/sort:block" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="m18 15-6-6-6 6" />
        </svg>
        <svg class="hidden size-4 group-data-[direction=descending]/sort:block" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="m6 9 6 6 6-6" />
        </svg>
    </span>
</button>

@props([
    // Text alignment for the cell. Unlike `table.head`, the default recipe
    // never baked in a `text-*` utility, so there was no stylesheet-order
    // hazard here — a consumer's own `class="text-end"` already won reliably.
    // The prop is added anyway so a numeric/action column can align its head
    // and cells through the same API instead of a prop on one and a raw
    // class on the other. `start` renders no alignment class, exactly
    // matching the previous (alignment-unset) output.
    'align' => 'start',
    'nowrap' => false,
])

@php
    $alignClasses = [
        'center' => 'text-center',
        'end' => 'text-end',
    ];
    $alignClass = $alignClasses[$align] ?? '';
@endphp

<td
    data-slot="table-cell"
    data-align="{{ $align }}"
    {{ $attributes->merge([
        'class' => trim(
            'px-3 py-2 align-middle'
            .($alignClass !== '' ? ' '.$alignClass : '')
            .($nowrap ? ' whitespace-nowrap' : '')
        ),
    ]) }}
>
    {{ $slot }}
</td>

@props([
    'state' => 'empty',
    'colspan' => 1,
    'heading' => null,
    'description' => null,
])

@php
    $isLoading = $state === 'loading';
    $heading ??= $isLoading ? 'Loading data…' : 'No results';
    $description ??= $isLoading
        ? 'Wait while the latest data loads.'
        : 'Try adjusting your search or filters.';
@endphp

<tr
    data-slot="table-state"
    data-state="{{ $isLoading ? 'loading' : 'empty' }}"
    aria-live="polite"
    aria-atomic="true"
    {{ $attributes }}
>
    <td colspan="{{ max(1, (int) $colspan) }}" class="px-3 py-12 text-center">
        <div class="mx-auto flex max-w-sm flex-col items-center gap-2">
            <span class="flex size-10 items-center justify-center rounded-full bg-muted text-muted-foreground" aria-hidden="true">
                @if ($isLoading)
                    <x-ui.spinner class="size-5" />
                @else
                    <svg class="size-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
                        <circle cx="11" cy="11" r="8" />
                        <path d="m21 21-4.3-4.3" stroke-linecap="round" stroke-linejoin="round" />
                    </svg>
                @endif
            </span>
            <p class="text-sm font-medium text-foreground">{{ __($heading) }}</p>
            <p class="text-sm text-muted-foreground">{{ __($description) }}</p>
            @if (! $slot->isEmpty())
                <div class="mt-2">{{ $slot }}</div>
            @endif
        </div>
    </td>
</tr>

/**
 * Table row link (`<x-ui.table.row href="…">`).
 *
 * The whole row is a pointer target, but the row keeps one real link: the
 * anchor in its primary cell (`data-row-link`, else the first `a[href]`).
 * Keyboard and screen-reader users reach that link as usual; a click on the
 * rest of the row forwards to it, so `wire:navigate` and other link handlers
 * still run. Clicks on buttons, inputs, labels, menus and other links inside
 * the row keep their own behaviour, and selecting text never navigates.
 */
const INTERACTIVE = [
    'a[href]',
    'button',
    'input',
    'select',
    'textarea',
    'label',
    'summary',
    'details',
    '[contenteditable]:not([contenteditable="false"])',
    '[role="button"]',
    '[role="checkbox"]',
    '[role="switch"]',
    '[role="menuitem"]',
    '[role="option"]',
    '[role="link"]',
    '[tabindex]:not([tabindex="-1"])',
    '[data-row-link-ignore]',
].join(',');

document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiTableRow', (config = {}) => ({
        href: config.href ?? '',

        link() {
            return this.$el.querySelector('a[data-row-link]')
                ?? Array.from(this.$el.querySelectorAll('a[href]')).find((anchor) => anchor.getAttribute('href') === this.href)
                ?? this.$el.querySelector('a[href]');
        },

        ignore(event) {
            const target = event.target instanceof Element ? event.target : null;
            if (!target || !this.$el.contains(target)) return true;
            const interactive = target.closest(INTERACTIVE);
            if (interactive && interactive !== this.$el && this.$el.contains(interactive)) return true;
            // A drag that selected text is a selection, not a click.
            const selection = window.getSelection?.();

            return Boolean(selection && !selection.isCollapsed && String(selection).trim() !== '' && this.$el.contains(selection.anchorNode));
        },

        open(event) {
            if (event.button > 1 || event.defaultPrevented || this.ignore(event)) return;
            const anchor = this.link();
            const url = anchor?.href ?? this.href;
            if (!url) return;

            // A modifier or middle click opens a new tab, as it would on the link.
            if (event.button === 1 || event.metaKey || event.ctrlKey || event.shiftKey) {
                event.preventDefault();
                window.open(url, '_blank', 'noopener');

                return;
            }
            if (event.button !== 0) return;

            if (anchor) {
                anchor.click();
            } else {
                window.location.assign(url);
            }
        },
    }));
});