Vue Component

Import

<script setup lang="ts">
    import {TableBuilder} from '@/components'
    import type {TableData} from '@/types/table-builder'

    defineProps<{ table: TableData }>()
</script>

<template>
    <TableBuilder :table="table"/>
</template>

The component is exported from the package's resources/js/components/ directory, which is aliased via @.

Props

Features Rendered

The component renders all of the following automatically based on what the PHP builder provides:

User Interactions

With the default inertia transport every interaction makes an Inertia visit with preserveState: true and preserveScroll: true so the page does not fully reload. With the http transport the same interactions change the in-memory query and refetch from source instead; the url is left alone. See HTTP Transport.

Search Debounce

Search inputs are debounced to avoid firing on every keystroke. The default is 350ms. Change it globally:

TableBuilder::defaultSearchDebounce(500); // ms

Dark Mode

The component respects the dark class on the <html> element and uses Tailwind's dark mode utilities throughout.

Customizing Appearance

Global cell/header classes

$table->class(cell: 'py-3 text-sm', head: 'bg-muted font-semibold');

Per-column classes

->column('id', 'ID', classes: 'w-16 tabular-nums')
->column('id', 'ID', classes: ['w-16' => true, 'hidden' => $compact])

The resolved classes arrive in the class key of the column payload.

CSS Variables

The package uses shadcn/ui-style CSS variables. Override in your app.css:

:root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    /* ... */
}

Row classes

Style rows from the table class with rowClass(). The callback gets the original row (the model, not the formatted array) and returns a string, a list of classes or a class => bool array:

$table->rowClass(fn (Message $message): array => [
    'font-semibold' => ! $message->is_seen,
    'text-muted-foreground' => $message->is_archived,
]);

The result travels as __class on each row, only for rows with a class and only when rowClass() is set. A row that already has a __class value throws a LogicException; alias that column in the query. The component merges it with the rowClass prop through tailwind-merge, prop last.

Auto-refresh

$table->poll(30) sends poll: 30, and the component reloads the rows every 30 seconds: with the inertia transport through router.reload(), with the http transport by a silent refetch of the current query. Sorting, search, filters, the page and the selection stay as they are.

It pauses while rows are selected, while a confirmation or choice dialog is open, while an action or request runs and while the tab is hidden. A tick missed while the tab was hidden runs as soon as it is visible again. Unmounting stops the timer. Without poll() the payload has no poll key and nothing is scheduled.

With the inertia transport, always pass only with the name of the table prop:

<TableBuilder :table="messages" :only="['messages']" />

Without it every tick reloads all props of the page, shared props included, and the component warns once in development.

Translations

The component reads its texts from the shared Inertia prop vue_table_builder_table_translations. useTranslations is exported from the package entry resources/js/index.ts, here aliased as @table-builder:

import {useTranslations} from '@table-builder'

const {t} = useTranslations('vue_mailbox_translations', {group: 'mailbox'})

t('mailbox::mailbox.compose.title')
t('compose.title')

Share the bundle from your own service provider, for the current locale:

Inertia::share('vue_mailbox_translations', fn () => trans('mailbox::mailbox'));

A vendor:: prefix is always stripped. group strips the file name the bundle was shared from; it defaults to table for the table builder's own bundle and to nothing for any other.

Slots

<TableBuilder :table="table">
    <template #cell-status="{value}">
        <Badge :variant="value === 'active' ? 'default' : 'secondary'">{{ value }}</Badge>
    </template>

    <template #actions="{row}">
        <Button size="sm" @click="edit(row)">Edit</Button>
    </template>

    <template #toolbar>
        <Button variant="outline" @click="openSettings">Settings</Button>
    </template>
</TableBuilder>

Without a cell-{key} slot the value is rendered with v-html. The PHP builder escapes string values before they are serialized, so that is safe for tables driven by the builder. It is not safe for rows fetched from an API with the http transport: escape those yourself, or render them through a cell-{key} slot.

Events

Reordering Rows

reorderable() in the Table class, or the reorderable prop, puts a drag handle in front of every row and emits reorder with {from, to, row} after a drop. See Reordering for storing the order on the server, how ties are broken and handling the event yourself.

Clicking Rows

A row with a row link from the PHP builder follows that link. Every other row emits row-click, and gets the pointer cursor as soon as a listener is bound, so an http table can open a record without a server-side row link. Clicks on the drag handle, the selection checkbox, the actions slot and columns marked clickable: false never reach it.

<TableBuilder :table="table" @row-click="({row}) => open(row)"/>

Nested Rows

The row-after slot renders below each row, for option lines or grouped sub-rows. colspan is the full width of a row including the handle, selection and actions columns, and columns are the visible columns. TableRow and TableCell are exported so those rows look like the rest of the table.

<script setup lang="ts">
    import {TableBuilder, TableCell, TableRow} from '@/components'
</script>

<template>
    <TableBuilder :table="table">
        <template #row-after="{row, colspan}">
            <TableRow v-for="option in row.options" :key="option.id" class="bg-muted/30">
                <TableCell :colspan="colspan" class="pl-10">{{ option.name }}</TableCell>
            </TableRow>
        </template>
    </TableBuilder>
</template>

Exposed Methods

<script setup lang="ts">
    import {useTemplateRef} from 'vue'

    const table = useTemplateRef('table')

    function refresh() {
        table.value?.reload()
    }
</script>

<template>
    <TableBuilder ref="table" :table="table"/>
</template>

TypeScript

Import types for use in your pages:

import type {TableData, Column, Filter, BulkAction, PaginationData} from '@/types/table-builder'

See TypeScript Types for the full interface reference.