Vue Query Builder Table

Vue 3 table component that talks to JSON endpoints and emits query parameters compatible with Spatie Laravel Query Builder.

This package does not depend on Inertia. Data loading is done with Axios by default, and the HTTP client can be injected.

Install

npm install @adesin-fr/vue-query-builder-table axios vue vuedraggable

Usage

<script setup lang="ts">
import { Table, type TableOptions } from "@adesin-fr/vue-query-builder-table";
import "@adesin-fr/vue-query-builder-table/dist/style.css";

const usersTable: TableOptions = {
  name: "users",
  endpoint: "/api/users",
  defaultSort: "name",
  globalSearch: "Search users...",
  columns: [
    { key: "name", label: "Name", sortable: true },
    { key: "email", label: "Email", sortable: true },
    { key: "created_at", label: "Created at", sortable: true },
  ],
  searchInputs: [
    { key: "name", label: "Name" },
    { key: "email", label: "Email" },
  ],
  filters: [
    { key: "created_at", label: "Created at", type: "date" },
  ],
};
</script>

<template>
  <Table :options="usersTable" />
</template>

Initial Data Props

The table can render initial data from props:

<Table
  :options="usersTable"
  :initial-data="users.data"
  :initial-meta="users.meta"
/>

You can also pass a Laravel paginator/API Resource object directly:

<Table
  :options="usersTable"
  :initial-resource="users"
/>

Short aliases are also supported for convenience:

<Table :options="usersTable" :data="users.data" :meta="users.meta" />
<Table :options="usersTable" :resource="users" />

When initial data is provided through props and options.autoLoad is omitted, the table does not perform an immediate initial request. User interactions such as sorting, filtering, searching, and pagination still use options.endpoint. Set autoLoad: true to force an immediate refresh.

Options Contract

The public contract is typed in TableOptions and exported from the package.

Important options:

• name: table name, defaults to default.
• endpoint: JSON endpoint used by Axios.
• queryPrefix: parameter prefix. Defaults to "" for default, otherwise ${name}_.
• pageName: pagination parameter. Defaults to page or ${name}Page.
• columns: column definitions.
• filters: select, toggle, number range, date, or number filters.
• searchInputs: Spatie filter[...] text inputs.
• globalSearch: adds a filter[global] input.
• httpClient: optional Axios-compatible client.
• responseDataPath and responseMetaPath: optional dot paths for custom payloads.
• Initial data can be passed either through options.data/options.meta/options.resource or through component props initialData/initialMeta/initialResource.

Request Shape

For a table named users, the default request shape is:

GET /api/users?users_filter[name]=john&users_sort=-created_at&usersPage=2&perPage=30

For name: "default":

GET /api/users?filter[name]=john&sort=-created_at&page=2&perPage=30

Response Shape

The component accepts Laravel paginator/API Resource shapes:

{
  "data": [],
  "links": { "next": null, "prev": null },
  "meta": { "total": 0, "per_page": 15 }
}

It also accepts a raw paginator with data, next_page_url, prev_page_url, and pagination metadata.

TypeScript

Types are declared once in js/types.ts and exported from the package entry:

import type {
  TableOptions,
  TableColumn,
  TableFilter,
  NormalizedResponse,
} from "@adesin-fr/vue-query-builder-table";

Shared helpers are also typed:

import { buildQueryParams, createTableOptions, normalizePaginatedResponse } from "@adesin-fr/vue-query-builder-table";

Migration From Inertia Package

• Replace queryBuilderProps from Inertia with a local options object.
• Replace Inertia visits with endpoint JSON requests.
• Keep Spatie-compatible filter/sort names by using queryPrefix and pageName.
• Use one endpoint per table for the simplest multi-table pages.