DataTable for Quasar

🇪🇸 Versión en español | 🇧🇷 Versão em português

Quasar extension with a homologated DataTable: shell over QTable, unified client/server pagination, and cards on viewports < sm.

Table of contents

• In 30 seconds
• What it is and what it includes
• Requirements and compatibility
• Install in a Quasar app
• What the extension adds to the host
• Global defaults (boot)
• Quick start
• Language (i18n)
• TypeScript in your IDE
• DataTable component API
• Client-side pagination
• Server-side pagination
• Mobile layout (grid / cards)
• Compact reference
• Public entrypoints
• Troubleshooting

In 30 seconds

1. Install the extension: quasar ext add @benjaminor-dev/datatable.
2. Import DataTable in your Vue component.
3. Pass rows, columns, row-key, and v-model:pagination.
4. Add client-pagination for built-in client pagination (or server-pagination + emits when you control the backend).

The extension registers CSS and a defaults boot in the host automatically.

What it is and what it includes

DataTable is a presentation layer over Quasar QTable: optional bordered shell, pagination bar (TablePaginationBar), and card layout on mobile.

• Client pagination (client-pagination) or server pagination (server-pagination + emits).
• Bar placement: auto | top | bottom | both (with auto, top bar only when the current page shows ≥ 15 rows).
• Built-in rows-per-page ladder (5…300) and “All” when applicable.
• Shared mobile breakpoint (useDataTableGridLayout) — cards below < 600px.
• #item slot for custom cards; default card included.
• Exportable helpers to orchestrate pagination in upper layers of your app.
• Built-in i18n en, es, pt — pagination bar follows $q.lang; optional boot overrides (locale, messages).

Requirements and compatibility

Install in a Quasar app

quasar ext add @benjaminor-dev/datatable

After quasar ext add, the extension registers CSS and the defaults boot automatically. No extra steps for a normal npm install.

Remove:

quasar ext remove @benjaminor-dev/datatable

Removes the generated defaults boot and its quasar.config entry. Stylesheet injection may remain if another installed package registers the same CSS path.

What the extension adds to the host

Install (quasar ext add / invoke): creates src/boot/bor/bor-datatable-defaults.ts (or .js) and registers it in quasar.config → boot: [] automatically. No manual editing needed in a normal install. main.css is injected on every dev/build (it does not appear as a short entry in quasar.config).

Remove (quasar ext remove): removes the defaults boot and its quasar.config entry when the extension created it.

Boot order (this extension):

1. bor/bor-datatable-defaults (host)
2. rest of your boots

In quasar.config you only see bor/bor-datatable-defaults; main.css is injected by the extension at compile time.

Global defaults (boot)

Edit src/boot/bor/bor-datatable-defaults.ts after install to pin locale or override pagination strings:

import { configureDataTableDefaults } from "@benjaminor-dev/quasar-app-extension-datatable";

configureDataTableDefaults({
  // locale: "es", // pin en | es | pt; omit to follow $q.lang
  // messages: { allRows: "Show all" },
});

configureDataTable is an alias of configureDataTableDefaults. Priority: boot locale → $q.lang.isoName → en; boot messages merge over the built-in catalog.

Quick start

<script setup lang="ts">
import { ref } from "vue";
import DataTable from "@benjaminor-dev/quasar-app-extension-datatable";
import type { ClientTablePaginationState } from "@benjaminor-dev/quasar-app-extension-datatable/types";

const rows = [
  { id: 1, name: "Ana", role: "Admin" },
  { id: 2, name: "Luis", role: "Editor" },
];

const columns = [
  { name: "name", label: "Name", field: "name", align: "left" as const },
  { name: "role", label: "Role", field: "role", align: "left" as const },
];

const pagination = ref<ClientTablePaginationState>({
  sortBy: "name",
  descending: false,
  page: 1,
  rowsPerPage: 10,
});
</script>

<template>
  <DataTable
    v-model:pagination="pagination"
    :rows="rows"
    :columns="columns"
    row-key="id"
    :client-pagination="{ defaultPageSize: 10 }"
  />
</template>

Language (i18n)

Built-in en, es, and pt. By default the pagination bar follows Quasar language ($q.lang.isoName); if Quasar has no language, fallback is en.

Locale resolution: boot locale → $q.lang.isoName prefix (es* → es, pt* → pt) → en.

Quasar config example (Spanish for the whole app):

// quasar.config.ts
framework: {
  lang: "es",
},

Built-in message keys: navigation aria labels, rows-per-page labels, page indicator ({page}, {lastPage}), range format ({start}, {end}, {total}), and allRows.

TypeScript in your IDE

Do not memorize the API — let autocomplete guide you.

• Import types from @benjaminor-dev/quasar-app-extension-datatable/types (or the main entry for components and helpers).

• In VS Code / Cursor: Ctrl+Space / Cmd+Space inside client-pagination or server-pagination to see valid props (DataTableClientPaginationConfig, DataTableServerPaginationConfig).

• Hover <DataTable> props: the tooltip shows JSDoc and Quasar QTable types where applicable.

• v-model:pagination is typed as ClientTablePaginationState — compatible with the QTable pagination model.

• useDataTableGridLayout() returns Ref<boolean>; with strict TS in templates, use computed(() => layoutRef.value) if :grid does not unwrap the ref.

• In configureDataTableDefaults({ … }) (boot), Ctrl+Space / Cmd+Space lists locale, messages, and DataTableMessages keys.

import DataTable, {
  useDataTableGridLayout,
  buildDynamicRowsPerPageOptions,
} from "@benjaminor-dev/quasar-app-extension-datatable";

import type {
  ClientTablePaginationState,
  DataTableServerPaginationConfig,
  DataTablePaginationPlacement,
} from "@benjaminor-dev/quasar-app-extension-datatable/types";

DataTable component API

Emits (server mode): pageSizeChange, first, previous, next, last.

Slots: item (grid card), top, bottom, standard QTable column slots.

Client-side pagination

<DataTable
  v-model:pagination="pagination"
  :rows="rows"
  :columns="columns"
  row-key="id"
  :client-pagination="{
    defaultPageSize: 10,
    placement: 'auto',
    pageSizeLadder: [5, 10, 25, 50],
  }"
/>

• The bar is hidden when totalRows does not exceed the first ladder step.
• Built-in ladder: “All” when 5 ≤ total ≤ 100.
• Custom pageSizeLadder: no “All” option.

Server-side pagination

The parent controls pagination and listens to emits. Pass derived state in server-pagination:

import type { DataTableServerPaginationConfig } from "@benjaminor-dev/quasar-app-extension-datatable/types";

const serverPagination = computed<DataTableServerPaginationConfig>(() => ({
  totalRows: store.total,
  pageSize: store.pageSize,
  lastPage: store.lastPage,
  pageSizeOptions: store.pageSizeOptions,
  rangeLabel: store.rangeLabel,
  enabled: store.hasSearched,
}));

The same helpers (buildDynamicRowsPerPageOptions, resolveDataTablePaginationPlacement, …) are exportable from this package.

Mobile layout (grid / cards)

By default, viewports ≤ 599px use grid layout (cards).

<script setup lang="ts">
import { computed } from "vue";
import { useDataTableGridLayout } from "@benjaminor-dev/quasar-app-extension-datatable";

const isMobileGridRef = useDataTableGridLayout();
const isMobileGrid = computed(() => isMobileGridRef.value);
</script>

<template>
  <DataTable :grid="isMobileGrid" ... />
</template>

Custom card via #item slot:

<template #item="props">
  <MyCard :row="props.row" :cols="props.cols" />
</template>

Compact reference

| configureDataTableDefaults | . / /types | Global i18n / locale boot | | ExtensionLocale | /types | "en" \| "es" \| "pt" |

Full type list and reexports: import /types and use IDE autocomplete.

If something is missing from autocomplete, check the import (/types vs main entry) before searching the README.

Public entrypoints

Troubleshooting

MIT © Benjamín Olvera R.