Table

QTable is a component that allows you to display data in a tabular manner. It’s generally called a datatable. It packs the following main features:

• Filtering
• Sorting
• Single / Multiple rows selection with custom selection actions
• Pagination (including server-side if required)
• Grid mode (you can use for example QCards to display data in a non-tabular manner)
• Total customization of rows and cells through scoped slots
• Ability to add additional row(s) at top or bottom of data rows
• Column picker (through QTableColumns component described in one of the sections)
• Custom top and/or bottom Table controls
• Responsive design

Defining the columns

Let’s take an example of configuring the columns property. We are going to tell QTable that row-key is ‘name’, which must be unique. If this was data fetched from a database we would likely use the row id.

columns: [
  // array of Objects
  // column Object definition
  {
    // unique id
    // identifies column
    // (used by pagination.sortBy, "body-cell-[name]" slot, ...)
    name: 'desc',

    // label for header
    label: 'Dessert (100g serving)',

    // row Object property to determine value for this column
    field: 'name',
    // OR field: row => row.some.nested.prop,

    // (optional) if we use visible-columns, this col will always be visible
    required: true,

    // (optional) alignment
    align: 'left',

    // (optional) tell QTable you want this column sortable
    sortable: true,

    // (optional) compare function if you have
    // some custom data or want a specific way to compare two rows
    // --> note that rows with null/undefined as value will get auto sorted
    // without calling this method (if you want to handle those as well, use "rawSort" instead)
    sort: (a, b, rowA, rowB) => parseInt(a, 10) - parseInt(b, 10),
    // function return value:
    //   * is less than 0 then sort a to an index lower than b, i.e. a comes first
    //   * is 0 then leave a and b unchanged with respect to each other, but sorted with respect to all different elements
    //   * is greater than 0 then sort b to an index lower than a, i.e. b comes first

    // (optional) requires Quasar v2.13+
    // compare function if you have
    // some custom data or want a specific way to compare two rows
    // --> note that there is an alternative "sort" method (above) if you don't
    // want to handle (by yourself) rows with null/undefined as value
    rawSort: (a, b, rowA, rowB) => parseInt(a, 10) - parseInt(b, 10),
    // has the same return value as the alternative "sort" method above

    // (optional) override 'column-sort-order' prop;
    // sets column sort order: 'ad' (ascending-descending) or 'da' (descending-ascending)
    sortOrder: 'ad', // or 'da'

    // (optional) you can format the data with a function
    format: (val, row) => `${val}%`,
    // one more format example:
    // format: val => val
    //   ? /* Unicode checkmark checked */ "\u2611"
    //   : /* Unicode checkmark unchecked */ "\u2610",

    // body td:
    style: 'width: 500px',
    // or as Function --> style: row => ... (return String/Array/Object)
    classes: 'my-special-class',
    // or as Function --> classes: row => ... (return String)

    // header th:
    headerStyle: 'width: 500px',
    headerClasses: 'my-special-class'
  },
  { name: 'calories', label: 'Calories', field: 'calories', sortable: true },
  { name: 'fat', label: 'Fat (g)', field: 'fat', sortable: true },
  { name: 'carbs', label: 'Carbs (g)', field: 'carbs' },
  { name: 'protein', label: 'Protein (g)', field: 'protein' },
  { name: 'sodium', label: 'Sodium (mg)', field: 'sodium' },
  {
    name: 'calcium',
    label: 'Calcium (%)',
    field: 'calcium',
    sortable: true,
    sort: (a, b) => parseInt(a, 10) - parseInt(b, 10)
  },
  {
    name: 'iron',
    label: 'Iron (%)',
    field: 'iron',
    sortable: true,
    sort: (a, b) => parseInt(a, 10) - parseInt(b, 10)
  }
]

Basic usage

Omitting columns definition

You can omit specifying the columns. QTable will infer the columns from the properties of the first row of the data. Note that labels are uppercased and sorting is enabled:

Sticky header/column

The footer slot (rendered as a real <tfoot> element) can be made sticky the same way. A good use case for it is a totals row:

Separators

Styling

Virtual scrolling

Notice that when enabling virtual scroll you will need to specify the table-style (with a max-height) prop. In the example below, we are also forcing QTable to display all rows at once (note the use of pagination and rows-per-page-options props).

You can dynamically load new rows when scroll reaches the end:

You can have both virtual scroll and pagination:

The example below shows how virtual scroll can be used along with a sticky header. Notice the virtual-scroll-sticky-start prop which is set to the header height.

Sticky columns work with virtual scroll too, with one precaution: scope any positional td selector (like td:first-child) to the data rows, as in the example below. Virtual scroll emulates the full height of the list through two hidden filler rows (q-virtual-scroll__padding), and their cells match such selectors as well; making them sticky breaks scrolling (dragging the scrollbar would run away to the end of the table).

There are 2 utility CSS classes that control VirtualScroll size calculation:

• Use q-virtual-scroll--with-prev class on an element rendered by the VirtualScroll to indicate that the element should be grouped with the previous one (main use case is for multiple table rows generated from the same row of data).
• Use q-virtual-scroll--skip class on an element rendered by the VirtualScroll to indicate that the element’s size should be ignored in size calculations.

Selection

Visible columns, custom top, fullscreen

Please note that columns marked as required (in the column definition) cannot be toggled and are always visible.

Popup editing

Editing with an input

Grid style

In the example below, we let QTable deal with displaying the grid mode (not using the specific slot):

However, if you want to fully customize the content, check the example below, where:

• We are using a Vue scoped slot called item to define how each record (the equivalent of a row in non-grid mode) should look. This allows you total freedom.
• We are using multiple selection.

Expanding rows

An external expansion model can also be used:

If you are using virtual scroll with QTable, you should know that there are 2 utility CSS classes that control VirtualScroll size calculation:

• Use q-virtual-scroll--with-prev class on an element rendered by the VirtualScroll to indicate that the element should be grouped with the previous one (main use case is for multiple table rows generated from the same row of data).
• Use q-virtual-scroll--skip class on an element rendered by the VirtualScroll to indicate that the element’s size should be ignored in size calculations.

Before/after slots

Note the difference between bottom-row and footer: the former renders extra rows inside the table body, while the latter renders a real <tfoot> element (which, for example, can be made sticky through CSS; see the “Sticky footer” example above).

Pagination

Below are two examples of handling the pagination (and sorting and rows per page).

The first example highlights how to configure the initial pagination:

The second example uses the “v-model:pagination” directive because we want to access its current value at any time. A use-case for the technique below can be to control the pagination from outside of QTable.

Pagination slot

For learning purposes, we will customize the pagination controls with the default controls in order to help you get started with your own.

Loading state

Custom top

Body slots

The example below shows how you can use a slot to customize the entire row:

Below, we use a slot which gets applied to each body cell:

You can also customize a particular column. The syntax for this slot is body-cell-[name], where [name] is the column’s name from the columns definition.

Header slots

The example below shows how you can use a slot to customize the entire header row:

Below, we use a slot which gets applied to each header cell:

You can also customize a particular header cell. The syntax for this slot is header-cell-[name], where [name] is the column’s name from the columns definition.

No data

There is also a “no-data” scoped slot (see below) that you can also to customize the messages for both when a filter doesn’t returns any results or the table has no data to display. Also type something into the “Search” input.

Handling bottom layer

There are a few properties that you can use to hide the bottom layer or specific parts of it. You can play with it below:

Custom sorting

Responsive tables

In order to create responsive tables, we have two tools at our disposal: dense and grid properties. We can connect these with $q.screen. More info: Screen Plugin.

First example below uses $q.screen.lt.md (for enabling dense mode) and the second examples uses $q.screen.xs to enable grid mode, so play with browser width to see them in action.

Server side pagination, filter and sorting

When your database contains a big number of rows for a Table, obviously it’s not feasible to load them all for multiple reasons (memory, UI rendering performance, …). Instead, you can load only a Table page. Whenever the user wants to navigate to another Table page, or wants to sort by a column or wants to filter the Table, a request is sent to the server to fetch the partially paged data.

1. First step to enable this behavior is to specify pagination prop, which MUST contain rowsNumber. QTable needs to know the total number of rows available in order to correctly render the pagination links. Should filtering cause the rowsNumber to change then it must be modified dynamically.

2. Second step is to listen for @request event on QTable. This event is triggered when data needs to be fetched from the server because either page number or sorting or filtering changed.

3. It’s best that you also specify the loading prop in order to notify the user that a background process is in progress.

Exporting data

Below is an example of a naive csv encoding and then exporting table data by using the exportFile Quasar util. The browser should trigger a file download. For a more professional approach in regards to encoding we do recommend using csv-parse and csv-stringify packages.

Accessibility

v2.25+

QTable renders a native <table> with thead/tbody, so the tabular semantics come for free. Sortable column headers are focusable, sort on Enter or Space and expose aria-sort; this behavior lives in QTh, so custom header/header-cell slots should render QTh rather than a plain th to keep it. The horizontally scrolling body is a Tab stop, so a wide table can be scrolled with the arrow keys. The selection checkboxes (and their otherwise empty column header), the pagination controls, the rows-per-page select and the loading progress bar carry localized accessible names from the Quasar Language Pack.

A few aspects remain in your hands:

• Clickable rows (@row-click & co.) are pointer-only: rows receive no focus and no key handling. Offer row actions as real buttons inside a cell, or add keyboard handling yourself — the Keyboard navigation example above shows the technique.
• grid mode trades the table semantics for plain cards.
• The title prop renders a visual heading, not a <caption> — associate a name with the table through aria-label/aria-labelledby if it needs one.

Keyboard navigation

Below is an example of keyboard navigation in the table using selected row. Use Arrow Up, Arrow Down, Page Up, Page Down, Home and End keys to navigate.