Inertia Table Documentation

Appearance

Upgrading ​

Inertia Table v4.x is the actively developed version. v3.x receives security fixes only. v2.x and v1.x are no longer supported.

Still on v3?

The v3 documentation is archived at inertiaui.com/inertia-table/legacy-docs.

Upgrading From v3.x to v4.x ​

Inertia Table v4.x drops support for older Laravel, Inertia, and React versions, removes deprecated APIs, replaces internal dependencies (@headlessui and axios) with lighter alternatives, and adds full TypeScript support.

Updated Requirements ​

  • Laravel: 12 or 13 (Laravel 10 and 11 are no longer supported)
  • Inertia Laravel: v2 or v3 (v1.x is no longer supported)
  • Inertia.js: v2 or v3 (v1 is no longer supported)
  • React: 19+ (React 18 is no longer supported)
  • Vue: 3.4+ (unchanged)
  • Inertia UI Modal: v2 or v3 (v0.x is no longer supported)

Upgrade Steps ​

Upgrade the Composer Package ​

bash
composer require inertiaui/table:^4.0

Reinstall the NPM Package ​

After upgrading the Composer package, reinstall the NPM package to pick up the new dependencies:

bash
npm install vendor/inertiaui/table/vue
bash
pnpm add file:vendor/inertiaui/table/vue
bash
npm install vendor/inertiaui/table/react
bash
pnpm add file:vendor/inertiaui/table/react

pnpm users

pnpm requires the file: protocol (pnpm add file:...) instead of a plain pnpm install. This ensures transitive dependencies like @inertiaui/vanilla are resolved correctly.

This pulls in @inertiaui/vanilla, which replaces @headlessui and axios internally. You may remove @headlessui/vue, @headlessui/react, @headlessui-float/vue, and axios from your project if they were only installed for Inertia Table.

Remove @tailwindcss/forms plugin ​

Inertia Table no longer requires the Tailwind Forms plugin. The necessary form resets are now built into the components. You may remove the @plugin '@tailwindcss/forms' directive from your CSS file if it was only installed for Inertia Table.

ESM-only Distribution ​

The NPM packages now ship only the ESM build. The legacy UMD file (dist/inertiaui-table.umd.js) has been removed. No change is required for Vite or Webpack projects.

Remove style.css import ​

Neither the Vue nor React packages ship a style.css file anymore. Remove these imports if you have them:

js
import '@inertiaui/table-vue/style.css'
import '@inertiaui/table-react/style.css'

Update withQueryBuilder() return type ​

The withQueryBuilder() method on the Table class now has an explicit return type. If you override this method, you need to update the signature:

php
public function withQueryBuilder(QueryBuilder $queryBuilder)
public function withQueryBuilder(QueryBuilder $queryBuilder): ?QueryBuilder
{
    // ...
}

Replace Exporter::withQuery() ​

The deprecated withQuery(callable) method on the Exporter class has been removed. Use withQueryBuilder() on your Table class instead.

Rename UnresolveabeRelationException ​

The exception class UnresolveabeRelationException has been renamed to UnresolvableRelationException to fix the typo. If you catch this exception by class name, update the reference.

Replace BadgeColumn::style() with variant() ​

The deprecated style() method on BadgeColumn has been removed. Use variant() instead.

Replace Deprecated Style and ActionStyle Enums ​

The Style and ActionStyle enums have been removed. Use Variant and ActionType instead. The style parameter on Action::make() has been removed; use the variant and type parameters instead. The serialized style key is no longer included in action and badge column data.

Replace Deprecated CSS Classes ​

The it-primary-button and it-primary-link CSS classes have been removed. Use it-info-button and it-info-link instead if you target these in custom CSS.

Replace Deprecated Button Props ​

The primary and danger props on the Button component have been removed. Use the variant prop with "info" or "danger" instead.

Update Custom Error Handlers ​

The error object passed to custom onError callbacks has changed because axios has been replaced by the native fetch API. The error is now a plain Error instead of an AxiosError:

js
// Error message format
"AxiosError: Request failed with status code 500"
"Error: HTTP 500"

// Accessing error details
error.response.data 
error.data 

// Accessing status code
error.response.status 
error.status

Pass the Resource to useTable() and useActions() ​

The useTable() and useActions() composables/hooks now require the table resource as an argument. This only affects you if you call them directly for custom layouts; the default <Table> component handles this internally.

In Vue, both composables accept either a plain TableResource, a Ref<TableResource>, or a getter function. A getter is the idiomatic choice when the resource comes from props (so updates flow through to useActions' reactive selection state):

js
// Vue
const table = useTable()
const table = useTable(() => props.resource)

const actions = useActions()
const actions = useActions(() => props.resource)
js
// React
const table = useTable()
const table = useTable(resource)

const actions = useActions()
const actions = useActions(resource)

Rename Topbar Slots ​

The topbarStart and topbarEnd slots (Vue) / props (React) have been replaced with four more granular slots: beforeSearch, afterSearch, beforeActions, and afterActions. The search input and buttons are now wrapped in separate <div> elements, so the gap between them is preserved when you inject content.

vue
<template #topbarStart>
<template #beforeSearch>

<template #topbarEnd>
<template #afterActions>

See the Slots documentation for the full layout diagram.

Add New Translation Keys ​

For custom translations via setTranslations(), the following keys have been added:

js
setTranslations({
    go_to_first_page: 'Go to first page',
    go_to_previous_page: 'Go to previous page',
    go_to_next_page: 'Go to next page',
    go_to_last_page: 'Go to last page',
    clear_all_filters: 'Clear all filters',
})

Confirmation dialogs for bulk actions support pluralization via arrays. See Row Actions for details.

Date Picker Translations ​

The date picker's month names, day abbreviations, AM/PM labels, and placeholder text are now translatable via setTranslations() using the date_picker_ prefix. See the Translations documentation for the full list of keys.

Upgrading From v2.x to v3.x ​

The only difference between v2.x and v3.x is the Tailwind CSS version. Inertia Table v3.x requires Tailwind CSS v4.x, while v2.x uses Tailwind CSS v3.x.

With Tailwind CSS v4.x, you no longer define the Inertia Table path in the content array of your tailwind.config.js file. Instead, you include it directly in your CSS file using the @source directive. You may also find this in the Tailwind CSS documentation.

Upgrading from v1.x to v2.x ​

There are three differences between v1.x and v2.x:

  • The installation process has changed.
  • The React and Vue NPM packages now have separate names.
  • The Vue package is now located in the vue directory instead of the js directory.

Below, you'll find more information on each of these changes, but you may also want to jump straight to the upgrade steps.

Installation Process ​

In v1.x, we used an alias in the vite.config.js file to link the NPM package. This has been replaced with the npm install command in v2.x. Using the npm install command results in a symlink being created in your node_modules directory to the package in the vendor directory. This makes it easier for Vite to tree-shake the package, resulting in a smaller bundle size. It's also more future-proof, as it doesn't rely on Vite-specific configuration.

NPM package names ​

In v1.x, both the Vue and React packages were named inertiaui/table. In v2.x, the Vue package is named @inertiaui/table-vue, and the React package is named @inertiaui/table-react. This change was made because inertiaui/table is actually not a valid NPM package name, as it's missing the @ symbol. This was not an issue in v1.x, as the package was aliased in the vite.config.js file. However, in v2.x, we've decided to use valid NPM package names to avoid any potential issues in the future. It's also more consistent with the Inertia Modal package, which uses the @inertiaui/modal-vue and @inertiaui/modal-react package names.

Vue Package Location ​

In v1.x, the Vue package was located in the js directory. In v2.x, it has been moved to the vue directory. At the initial release, there was only a Vue package, and the React package was added later. To avoid breaking changes at that time, we decided to keep the Vue package in the js directory. However, now that we have separate package names for Vue and React, we've decided to move the Vue package to the vue directory to make it more consistent with the React package.

Upgrade Steps ​

Upgrading from v1.x to v2.x is a fairly straightforward process and should only take a few minutes.

Remove the Custom Configuration From vite.config.js ​

The alias and dedupe configurations in the vite.config.js file are no longer necessary. You may remove them from your configuration file.

js
resolve: {
    alias: {'inertiaui/table': '/vendor/inertiaui/table/js'},
    dedupe: ['@inertiajs/vue3']
}
js
resolve: {
    alias: {'inertiaui/table': '/vendor/inertiaui/table/react'},
    dedupe: ['@inertiajs/react']
}

Upgrade the Composer Package ​

Upgrade the Composer package via:

bash
composer require inertiaui/table:^2.0

Install the NPM Package ​

After upgrading the Composer package, install the NPM package:

bash
npm install vendor/inertiaui/table/vue
bash
pnpm add file:vendor/inertiaui/table/vue
bash
npm install vendor/inertiaui/table/react
bash
pnpm add file:vendor/inertiaui/table/react

pnpm users

pnpm requires the file: protocol (pnpm add file:...) instead of a plain pnpm install.

Update Your Imports ​

You'll need to update your imports to use the new package names:

js
import { Table } from 'inertiaui/table'
import { Table } from '@inertiaui/table-vue'
js
import { Table } from 'inertiaui/table'
import { Table } from '@inertiaui/table-react'

The styles have also been moved to the new package names, and there's no need to include the dist directory in the import path:

js
import 'inertiaui/table/dist/style.css'
import '@inertiaui/table-vue/style.css'
js
import 'inertiaui/table/dist/style.css'
import '@inertiaui/table-react/style.css'

Update Your Tailwind Configuration (Vue only) ​

You need to include the new package path in the content array of your tailwind.config.js file:

js
export default {
    content: [
        './vendor/inertiaui/table/js/src/**/*.vue',
        './vendor/inertiaui/table/vue/src/**/*.vue',
    ]
}

That's it! There's no need to update anything on the PHP side, and except for updating the imports, there should be no other changes required on the front end either.