--- title: Table related: - title: Markup Table path: markup-table.md - title: Pagination path: pagination.md --- 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 > [!TIP] > If you don't need pagination, sorting, filtering, and all other features of QTable, then you may want to check out [QMarkupTable](markup-table.md) component instead. ## QTable API ### Props - `fullscreen` (boolean, optional, syncable) Fullscreen mode Required to be used with v-model. Examples: `v-model:fullscreen="isFullscreen"` - `no-route-fullscreen-exit` (boolean, optional) Changing route app won't exit fullscreen - `rows` (any[], required) Rows of data to display Examples: `:rows="myData"` - `row-key` (string | Function, optional), default `'id'` Property of each row that defines the unique key of each row (the result must be a primitive, not Object, Array, etc); The value of property must be string or a function taking a row and returning the desired (nested) key in the row; If supplying a function then for best performance, reference it from your scope and do not define it inline Function signature: `(row?: object) => any` Examples: `'name'`, `row => row.name` Params: - `row` (object, optional) The current row being processed Examples: - `{ name: 'Lorem Ipsum', price: 19 }` Returns: `any` Current row's key Examples: `'34f39dda-6206-4071-a9df-4393aabe49ac'`, `34` - `virtual-scroll` (boolean, optional) Display data using QVirtualScroll (for non-grid mode only) - `virtual-scroll-target` (Element | string | ComponentInstance, optional) CSS selector, DOM element or Vue component reference (standing for its root element) to be used as a custom scroll container instead of the auto detected one Examples: - `.scroll-target-class` - `#scroll-target-id` - `$refs.scrollTarget` - `$refs.scrollAreaComponent` - `document.body` - `virtual-scroll-slice-size` (number | string, optional), default `10` Minimum number of rows to render in the virtual list - `virtual-scroll-slice-ratio-before` (number | string, optional), default `1` Ratio of number of rows in visible zone to render before it - `virtual-scroll-slice-ratio-after` (number | string, optional), default `1` Ratio of number of rows in visible zone to render after it - `virtual-scroll-item-size` (number | string, optional), default `48/24` Default size in pixels of a row; This value is used for rendering the initial table; Try to use a value close to the minimum size of a row; Default value: 48 (24 if dense) - `virtual-scroll-sticky-size-start` (number | string, optional), default `0` Size in pixels of the sticky header (if using one); A correct value will improve scroll precision; Will be also used for non-virtual-scroll tables for fixing top alignment when using scrollTo method - `virtual-scroll-sticky-size-end` (number | string, optional), default `0` Size in pixels of the sticky footer part (if using one); A correct value will improve scroll precision - `table-colspan` (number | string, optional) The number of columns in the table (you need this if you use table-layout: fixed) - `color` (string, optional), default `'grey-8'` Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `icon-first-page` (string, optional) Icon name following Quasar convention for stepping to first page; Make sure you have the icon library installed unless you are using 'img:' prefix Examples: `'map'`, `'ion-add'`, `'img:https://cdn.quasar.dev/logo-v2/svg/logo.svg'`, `'img:path/to/some_image.png'` - `icon-prev-page` (string, optional) Icon name following Quasar convention for stepping to previous page; Make sure you have the icon library installed unless you are using 'img:' prefix Examples: `'map'`, `'ion-add'`, `'img:https://cdn.quasar.dev/logo-v2/svg/logo.svg'`, `'img:path/to/some_image.png'` - `icon-next-page` (string, optional) Icon name following Quasar convention for stepping to next page; Make sure you have the icon library installed unless you are using 'img:' prefix Examples: `'map'`, `'ion-add'`, `'img:https://cdn.quasar.dev/logo-v2/svg/logo.svg'`, `'img:path/to/some_image.png'` - `icon-last-page` (string, optional) Icon name following Quasar convention for stepping to last page; Make sure you have the icon library installed unless you are using 'img:' prefix Examples: `'map'`, `'ion-add'`, `'img:https://cdn.quasar.dev/logo-v2/svg/logo.svg'`, `'img:path/to/some_image.png'` - `grid` (boolean, optional) Display data as a grid instead of the default table - `grid-header` (boolean, optional) Display header for grid-mode also - `dense` (boolean, optional) Dense mode; Connect with $q.screen for responsive behavior - `columns` (any[], optional) The column definitions (Array of Objects) Examples: `:columns="tableColumns"` Object shape: - `name` (string, required) Unique id, identifies column, (used by pagination.sortBy, 'body-cell-[name]' slot, ...) Examples: `'desc'` - `label` (string, required) Label for header Examples: `'Dessert (100g serving)'` - `field` (string | Function, required) Row Object property to determine value for this column or function which maps to the required property Function signature: `(row: object) => any` Examples: `'name'`, `row => row.prices.active` Params: - `row` (object, required) The current row being processed Examples: - `{ name: 'Lorem Ipsum', prices: { active: 19, old: 25, list: 29 } }` Returns: `any` Value for this column Examples: `'19'`, `19` - `required` (boolean, optional) If we use visible-columns, this col will always be visible - `align` (string, optional), default `'right'` Horizontal alignment of cells in this column Accepts: `'left'`, `'right'`, `'center'` - `sortable` (boolean, optional), default `false` Tell QTable you want this column sortable - `sort` (Function, optional) Compare function if you have some custom data or want a specific way to compare two rows; rows with null/undefined values will get sorted without triggering this method (use 'rawSort' instead if you want to handle those values too) Function signature: `(a: any, b: any, rowA: object, rowB: object) => number` Examples: - `(a, b, _rowA, _rowB) => parseInt(a, 10) - parseInt(b, 10)` Params: - `a` (any, required) Value of the first comparison term Examples: `123`, `'abc'` - `b` (any, required) Value of the second comparison term Examples: `123`, `'abc'` - `rowA` (object, required) Full Row object in which is contained the first term Examples: - `{ name: 'Potassium', value: 'K' }` - `rowB` (object, required) Full Row object in which is contained the second term Examples: - `{ name: 'Fluorine', value: 'F' }` Returns: `number` Comparison result of term 'a' with term 'b'. Less than 0 when 'a' should come first; greater than 0 if 'b' should come first; equal to 0 if their position must not be changed with respect to each other Examples: `-1`, `0`, `1` - `rawSort` (Function, optional) *(added v2.13)* Compare function if you have some custom data or want a specific way to compare two rows; includes rows with null/undefined values (use 'sort' instead if you don't want that) Function signature: `(a: any, b: any, rowA: object, rowB: object) => number` Examples: - `(a, b, _rowA, _rowB) => parseInt(a, 10) - parseInt(b, 10)` Params: - `a` (any, required) Value of the first comparison term Examples: `123`, `'abc'` - `b` (any, required) Value of the second comparison term Examples: `123`, `'abc'` - `rowA` (object, required) Full Row object in which is contained the first term Examples: - `{ name: 'Potassium', value: 'K' }` - `rowB` (object, required) Full Row object in which is contained the second term Examples: - `{ name: 'Fluorine', value: 'F' }` Returns: `number` Comparison result of term 'a' with term 'b'. Less than 0 when 'a' should come first; greater than 0 if 'b' should come first; equal to 0 if their position must not be changed with respect to each other Examples: `-1`, `0`, `1` - `sortOrder` (string, optional), default `'ad'` Set column sort order: 'ad' (ascending-descending) or 'da' (descending-ascending); Overrides the 'column-sort-order' prop Accepts: `'ad'`, `'da'` - `format` (Function, optional) Function you can apply to format your data Function signature: `(val: any, row: object) => any` Examples: - `(val, _row) => `${ val }%`` - `val => val ? /* Unicode checkmark checked */ '☑' : /* Unicode checkmark unchecked */ '☐'` Params: - `val` (any, required) Value of the cell Examples: `123`, `'abc'` - `row` (object, required) Full Row object in which the cell is contained Examples: - `{ name: 'Potassium', value: 'K' }` Returns: `any` The resulting formatted value Examples: `'20%'` - `style` (string | Function, optional) Style to apply on normal cells of the column Function signature: `(row: object) => string` Examples: `'width: 500px'`, `row => (row.calories % 2 === 0 ? 'width: 10px' : 'font-size: 2em; font-weight: bold')` Params: - `row` (object, required) The current row being processed Examples: - `{ name: 'Frozen Yogurt', calories: 159 }` Returns: `string` - `classes` (string | Function, optional) Classes to add on normal cells of the column Function signature: `(row: object) => string` Examples: `'my-special-class bg-primary'`, `row => (row.calories % 2 === 0 ? 'bg-green text-white' : 'bg-yellow')` Params: - `row` (object, required) The current row being processed Examples: - `{ name: 'Frozen Yogurt', calories: 159 }` Returns: `string` - `headerStyle` (string, optional) Style to apply on header cells of the column Examples: `'width: 500px'` - `headerClasses` (string, optional) Classes to add on header cells of the column Examples: `'my-special-class'` - `autoWidth` (boolean, optional) *(added v2.31)* Tries to shrink the column to the minimum width required by its content (header and body cells alike) - `visible-columns` (any[], optional) Array of Strings defining column names ('name' property of each column from 'columns' prop definitions); Columns marked as 'required' are not affected by this property Examples: - `['desc', 'carbs', 'protein']` - `:visible-columns="myCols"` - `loading` (boolean, optional) Put Table into 'loading' state; Notify the user something is happening behind the scenes - `title` (string, optional) Table title Examples: `'Device list'` - `hide-header` (boolean, optional) Hide table header layer - `hide-bottom` (boolean, optional) Hide table bottom layer regardless of what it has to display - `hide-selected-banner` (boolean, optional) Hide the selected rows banner (if any) - `hide-no-data` (boolean, optional) Hide the default no data bottom layer - `hide-pagination` (boolean, optional) Hide the pagination controls at the bottom - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `flat` (boolean, optional) Applies a 'flat' design (no default shadow) - `bordered` (boolean, optional) Applies a default border to the component - `square` (boolean, optional) Removes border-radius so borders are squared - `separator` (string, optional), default `'horizontal'` Use a separator/border between rows, columns or all cells Accepts: `'horizontal'`, `'vertical'`, `'cell'`, `'none'` - `wrap-cells` (boolean, optional) Wrap text within table cells - `binary-state-sort` (boolean, optional) Skip the third state (unsorted) when user toggles column sort direction - `column-sort-order` (string, optional), default `'ad'` Set column sort order: 'ad' (ascending-descending) or 'da' (descending-ascending); It gets applied to all columns unless a column has its own sortOrder specified in the 'columns' definition prop Accepts: `'ad'`, `'da'` - `no-data-label` (string, optional) Override default text to display when no data is available Examples: `'No devices available'` - `no-results-label` (string, optional) Override default text to display when user filters the table and no matched results are found Examples: `'No matched records'` - `loading-label` (string, optional) Override default text to display when table is in loading state (see 'loading' prop) Examples: `'Loading devices...'` - `selected-rows-label` (Function, optional) Text to display when user selected at least one row; For best performance, reference it from your scope and do not define it inline Function signature: `(numberOfRows?: number) => string` Examples: `(numberOfRows) => `Selected: ${ numberOfRows } entries`` Params: - `numberOfRows` (number, optional) Number of rows available Returns: `string` Label to display Examples: `'5 rows are selected'` - `rows-per-page-label` (string, optional) Text to override default rows per page label at bottom of table; also used as the 'aria-label' of the rows per page selection field Examples: `'Records per page:'` - `pagination-label` (Function, optional) Text to override default pagination label at bottom of table (unless 'pagination' scoped slot is used); For best performance, reference it from your scope and do not define it inline Function signature: `(firstRowIndex?: number, endRowIndex?: number, totalRowsNumber?: number) => string` Examples: - `(start, end, total) => `${ start }-${ end } of ${ total }`` Params: - `firstRowIndex` (number, optional) Index of first displayed row - `endRowIndex` (number, optional) Index of last displayed row - `totalRowsNumber` (number, optional) Number of total rows available in data Returns: `string` Label to display Examples: `'1-10 of 132'` - `table-style` (string | any[] | object, optional) CSS style to apply to native HTML element's wrapper (which is a DIV) Examples: `'background-color: #ff0000'`, `{ backgroundColor: '#ff0000' }` - `table-class` (string | any[] | object, optional) CSS classes to apply to native HTML
element's wrapper (which is a DIV) Examples: `'my-special-class'`, `{ 'my-special-class': true }` - `table-header-style` (string | any[] | object, optional) CSS style to apply to header of native HTML
(which is a TR) Examples: `'background-color: #ff0000'`, `{ backgroundColor: '#ff0000' }` - `table-header-class` (string | any[] | object, optional) CSS classes to apply to header of native HTML
(which is a TR) Examples: `'my-special-class'`, `{ 'my-special-class': true }` - `table-row-style-fn` (Function, optional) *(added v2.18)* CSS style to apply to the table rows (which are TR elements); For best performance, reference it from your scope and do not define it inline Function signature: `(row?: object) => string` Params: - `row` (object, optional) The current row being processed Examples: - `{ name: 'Frozen Yogurt', calories: 159 }` Returns: `string` CSS style to apply to the row Examples: `'color: blue'`, `'background-color: #ff0000; color: green'` - `table-row-class-fn` (Function, optional) *(added v2.18)* CSS class(es) to apply the table rows (which are TR elements); For best performance, reference it from your scope and do not define it inline Function signature: `(row?: object) => string` Params: - `row` (object, optional) The current row being processed Examples: - `{ name: 'Frozen Yogurt', calories: 159 }` Returns: `string` CSS class(es) to apply to the row, space separated Examples: `'my-special-class'`, `'my-class my-second-class'` - `card-container-style` (string | any[] | object, optional) CSS style to apply to the cards container (when in grid mode) Examples: `'background-color: #ff0000'`, `{ backgroundColor: '#ff0000' }` - `card-container-class` (string | any[] | object, optional) CSS classes to apply to the cards container (when in grid mode) Examples: `'my-special-class'`, `'justify-center'`, `{ 'my-special-class': true }` - `card-style` (string | any[] | object, optional) CSS style to apply to the card (when in grid mode) or container card (when not in grid mode) Examples: `'background-color: #ff0000'`, `{ backgroundColor: '#ff0000' }` - `card-class` (string | any[] | object, optional) CSS classes to apply to the card (when in grid mode) or container card (when not in grid mode) Examples: `'my-special-class'`, `{ 'my-special-class': true }` - `card-style-fn` (Function, optional) *(added v2.18)* (Grid mode only) CSS style to apply to the row/record card; Has no effect when the 'item' slot is used; For best performance, reference it from your scope and do not define it inline Function signature: `(row?: object) => string` Params: - `row` (object, optional) The current row/record being processed Examples: - `{ name: 'Frozen Yogurt', calories: 159 }` Returns: `string` CSS style to apply to the row/record Examples: `'color: blue'`, `'background-color: #ff0000; color: green'` - `card-class-fn` (Function, optional) *(added v2.18)* (Grid mode only) CSS class(es) to apply the row/record card; Has no effect when the 'item' slot is used; For best performance, reference it from your scope and do not define it inline Function signature: `(row?: object) => string` Params: - `row` (object, optional) The current row/record being processed Examples: - `{ name: 'Frozen Yogurt', calories: 159 }` Returns: `string` CSS class(es) to apply to the row, space separated Examples: `'my-special-class'`, `'my-class my-second-class'` - `title-class` (string | any[] | object, optional) CSS classes to apply to the title (if using 'title' prop) Examples: `'my-special-class'`, `'text-h1'`, `{ 'text-h1': true }` - `filter` (string | object, optional) String/Object to filter table with; When using an Object it requires 'filter-method' to also be specified since it will be a custom filtering Examples: `'car'` - `filter-method` (Function, optional) The actual filtering mechanism; For best performance, reference it from your scope and do not define it inline Function signature: `(rows?: any[], terms?: string | object, cols?: any[], getCellValue?: Function) => any[]` Examples: `see source code` Params: - `rows` (any[], optional) Array of rows - `terms` (string | object, optional) Terms to filter with (is essentially the 'filter' prop value) - `cols` (any[], optional) Column definitions - `getCellValue` (Function, optional) Optional function to get a cell value Function signature: `(col: object, row: object) => any` Params: - `col` (object, required) Column entry from column definitions - `row` (object, required) The row object Returns: `any` Parsed/Processed cell value Examples: `'Ice Cream Sandwich'` Returns: `any[]` Filtered rows - `pagination` (object, optional, syncable) Pagination object; You can also use the 'v-model:pagination' for synching; When not synching it simply initializes the pagination on first render Examples: `:pagination="myInitialPagination"`, `v-model:pagination="myPagination"` Object shape: - `sortBy` (string, optional) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, optional) Is sorting in descending order? - `page` (number, optional) Page number (1-based) - `rowsPerPage` (number, optional) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. If set, causes the QTable to emit @request when data is required. - `rows-per-page-options` (any[], optional), default `[5, 7, 10, 15, 20, 25, 50, 0]` Options for user to pick (Numbers); Number 0 means 'Show all rows in one page' Examples: - `[10, 20]` - `selection` (string, optional), default `'none'` Selection type Accepts: `'single'`, `'multiple'`, `'none'` - `selected` (any[], optional, syncable), default `[]` Keeps the user selection array Examples: `v-model:selected="selection"` - `expanded` (any[], optional, syncable) Keeps the array with expanded rows keys Examples: `v-model:expanded="expanded"` - `sort-method` (Function, optional) The actual sort mechanism. Function (rows, sortBy, descending) => sorted rows; For best performance, reference it from your scope and do not define it inline Function signature: `(rows?: any[], sortBy?: string, descending?: boolean) => any[]` Examples: `see source code` Params: - `rows` (any[], optional) Array with rows - `sortBy` (string, optional) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, optional) Is sorting in descending order? Returns: `any[]` Sorted rows ### Computed Props - `filteredSortedRows` (any[], optional) The filtered and sorted rows (same as the rows prop if using server-side fetching) Examples: - `[{ name: 'Ice Cream Sandwich', calories: 237, fat: 9.0, carbs: 37, protein: 4.3, sodium: 129, calcium: 8, iron: 1 }, ...]` - `computedRows` (any[], optional) Paginated, filtered, and sorted rows (same as the rows prop if using server-side fetching) Examples: - `[{ name: 'Ice Cream Sandwich', calories: 237, fat: 9.0, carbs: 37, protein: 4.3, sodium: 129, calcium: 8, iron: 1 }, ...]` - `computedRowsNumber` (number, optional) The number of computed rows ### Methods - `toggleFullscreen(): void` Toggles fullscreen mode - `setFullscreen(): void` Enter the fullscreen view - `exitFullscreen(): void` Leave the fullscreen view - `requestServerInteraction(props?: object): void` Trigger a server request (emits 'request' event) Params: - `props` (object, optional) Request details Object shape: - `pagination` (object, optional) Optional pagination object Object shape: - `sortBy` (string, optional) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, optional) Is sorting in descending order? - `page` (number, optional) Page number (1-based) - `rowsPerPage` (number, optional) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `filter` (Function, optional) Filtering method (the 'filter-method' prop) Function signature: `(rows: any[], terms: string | object, cols?: any[], getCellValue?: Function) => any[]` Params: - `rows` (any[], required) Array of rows - `terms` (string | object, required) Terms to filter with (is essentially the 'filter' prop value) - `cols` (any[], optional) Optional column definitions - `getCellValue` (Function, optional) Optional function to get a cell value Function signature: `(col: object, row: object) => any` Params: - `col` (object, required) Column entry from column definitions - `row` (object, required) The row object Returns: `any` Parsed/Processed cell value Examples: `'Ice Cream Sandwich'` Returns: `any[]` Filtered rows - `setPagination(pagination: object, forceServerRequest?: boolean): void` Unless using an external pagination Object (through 'v-model:pagination' prop), you can use this method and force the internal pagination to change Params: - `pagination` (object, required) Pagination object Object shape: - `sortBy` (string, optional) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, optional) Is sorting in descending order? - `page` (number, optional) Page number (1-based) - `rowsPerPage` (number, optional) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `forceServerRequest` (boolean, optional) Also force a server request - `firstPage(): void` Navigates to first page - `prevPage(): void` Navigates to previous page, if available - `nextPage(): void` Navigates to next page, if available - `lastPage(): void` Navigates to last page - `isRowSelected(key: any): boolean` Determine if a row has been selected by user Params: - `key` (any, required) Row key value Examples: `'calories'` Returns: `boolean` Is row selected or not? - `clearSelection(): void` Clears user selection (emits 'update:selected' with empty array) - `isRowExpanded(key: any): boolean` Determine if a row is expanded or not Params: - `key` (any, required) Row key value Examples: `'calories'` Returns: `boolean` Is row expanded or not? - `setExpanded(expanded: any[]): void` Sets the expanded rows keys array; Especially useful if not using an external 'expanded' state otherwise just emits 'update:expanded' with the value Params: - `expanded` (any[], required) Array containing keys of the expanded rows Examples: - `['row-a', 'row-b']` - `sort(col: string | object): void` Trigger a table sort Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `resetVirtualScroll(): void` Resets the virtual scroll (if using it) computations; Needed for custom edge-cases - `scrollTo(index: number | string, edge?: string): void` Scroll the table to the row with the specified index in page (0 based) Params: - `index` (number | string, required) The index of the row in page (0 based) - `edge` (string, optional), default `end/start` Only for virtual scroll - the edge to align to if the row is not visible already; If the '-force' version is used then it always aligns; Default value: end (if scrolling towards the end) / start (if scrolling towards the start) Accepts: `'start'`, `'center'`, `'end'`, `'start-force'`, `'center-force'`, `'end-force'` - `getCellValue(colName: string, row: object): any` Method to get a cell value Function signature: `(colName: string, row: object) => any` Params: - `colName` (string, required) Column name - `row` (object, required) The row object Returns: `any` Parsed/Processed cell value Examples: `'Ice Cream Sandwich'` ### Events - `@fullscreen` Emitted when fullscreen state changes Params: - `value` (boolean, optional) Fullscreen state (showing/hidden) - `@update:fullscreen` Used by Vue on 'v-model:fullscreen' prop for updating its value Params: - `value` (boolean, optional) Fullscreen state (showing/hidden) - `@row-click` Emitted when user clicks/taps on a row; Is not emitted when using body/row/item scoped slots Params: - `evt` (Event, optional) JS event object - `row` (object, optional) The row upon which user has clicked/tapped - `index` (number, optional) Index of the row in the current page - `@row-dblclick` Emitted when user quickly double clicks/taps on a row; Is not emitted when using body/row/item scoped slots; Please check JS dblclick event support before using Params: - `evt` (Event, optional) JS event object - `row` (object, optional) The row upon which user has double clicked/tapped - `index` (number, optional) Index of the row in the current page - `@row-contextmenu` Emitted when user right clicks/long taps on a row; Is not emitted when using body/row/item scoped slots Params: - `evt` (Event, optional) JS event object - `row` (object, optional) The row upon which user has right clicked/long tapped - `index` (number, optional) Index of the row in the current page - `@request` Emitted when a server request is triggered Params: - `requestProp` (object, optional) Props of the request Object shape: - `pagination` (object, required) Pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `filter` (string | object, optional) String/Object to filter table with (the 'filter' prop) - `getCellValue` (Function, required) Function to get a cell value Function signature: `(col: object, row: object) => any` Params: - `col` (object, required) Column entry from column definitions - `row` (object, required) The row object Returns: `any` Parsed/Processed cell value Examples: `'Ice Cream Sandwich'` - `@selection` Emitted when user selects/unselects row(s) Params: - `details` (object, optional) Selection details Object shape: - `rows` (any[], required) Array of row objects that were selected/unselected - `keys` (any[], required) Array of the keys of rows that were selected/unselected - `added` (boolean, required) Were the rows added to selection (true) or removed from selection (false) - `evt` (Event, required) JS event object - `@update:pagination` Used by Vue on 'v-model:pagination' for updating its value Params: - `newPagination` (object, optional) The updated pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `@update:selected` Used by Vue on 'v-model:selected' prop for updating its value Params: - `newSelected` (any[], optional) The updated selected array Examples: - `[{ name: 'Frozen Yogurt', calories: 159, fat: 6 }]` - `@update:expanded` Used by Vue on 'v-model:expanded' prop for updating its value Params: - `newExpanded` (any[], optional) The updated expanded array Examples: - `['row-a', 'row-b']` - `@virtual-scroll` Emitted when the virtual scroll occurs, if using virtual scroll Params: - `details` (object, optional) Object of properties on the new scroll position Object shape: - `index` (number, required) Index of the list item that was scrolled into view (0 based) - `from` (number, required) The index of the first list item that is rendered (0 based) - `to` (number, required) The index of the last list item that is rendered (0 based) - `direction` (string, required) Direction of change Accepts: `'increase'`, `'decrease'` - `ref` (ComponentInstance, required) Vue reference to the underlying QVirtualScroll instance ### Slots - `#loading` Override default effect when table is in loading state; Suggestion: QInnerLoading ### Scoped Slots - `#item` Slot to use for defining an item when in 'grid' mode; Suggestion: QCard Scope: - `key` (any, optional) Row/Item's key - `row` (object, optional) Row/Item object - `rowIndex` (number, optional) Row/Item's index (0 based) in the filtered and sorted table - `pageIndex` (number, optional) Row/Item's index (0 based) in the current page of the filtered and sorted table - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row/item selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row/item expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `#body` Slot to define how a body row looks like; Suggestion: QTr + Td Scope: - `key` (any, optional) Row's key - `row` (object, optional) Row object - `rowIndex` (number, optional) Row's index (0 based) in the filtered and sorted table - `pageIndex` (number, optional) Row's index (0 based) in the current page of the filtered and sorted table - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `__trClass` (string, optional) Internal prop passed down to QTr (if used) - `__trStyle` (string, optional) *(added v2.18)* Internal prop passed down to QTr (if used) - `#body-cell` Slot to define how all body cells look like; Suggestion: QTd Scope: - `col` (object, optional) Column definition for column associated with table cell - `value` (any, optional) Parsed/Formatted value of table cell - `key` (any, optional) Row's key - `row` (object, optional) Row object - `rowIndex` (number, optional) Row's index (0 based) in the filtered and sorted table - `pageIndex` (number, optional) Row's index (0 based) in the current page of the filtered and sorted table - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `#body-cell-[name]` Slot to define how a specific column cell looks like; replace '[name]' with column name (from columns definition object) Scope: - `col` (object, optional) Column definition for column associated with table cell - `value` (any, optional) Parsed/Formatted value of table cell - `key` (any, optional) Row's key - `row` (object, optional) Row object - `rowIndex` (number, optional) Row's index (0 based) in the filtered and sorted table - `pageIndex` (number, optional) Row's index (0 based) in the current page of the filtered and sorted table - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `#header` Slot to define how header looks like; Suggestion: QTr + QTh Scope: - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `__trClass` (string, optional) Internal prop passed down to QTr (if used) - `header` (boolean, optional) Internal prop passed down to QTh (if used); Always 'true' - `#header-cell` Slot to define how each header cell looks like; Suggestion: QTh Scope: - `col` (object, optional) Column definition associated to header cell - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `#header-cell-[name]` Slot to define how a specific header cell looks like; replace '[name]' with column name (from columns definition object) Scope: - `col` (object, optional) Column definition associated to header cell - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `#body-selection` Slot to define how body selection column looks like; Suggestion: QCheckbox Scope: - `key` (any, optional) Row's key - `row` (object, optional) Row object - `rowIndex` (number, optional) Row's index (0 based) in the filtered and sorted table - `pageIndex` (number, optional) Row's index (0 based) in the current page of the filtered and sorted table - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `#header-selection` Slot to define how header selection column looks like (available only for multiple selection mode); Suggestion: QCheckbox Scope: - `cols` (object, optional) Column definitions - `colsMap` (object, optional) Column mapping (key is column name, value is column object) - `sort` (Function, optional) Trigger a table sort Function signature: `(col: string | object) => void` Params: - `col` (string | object, required) Column name or column definition object Examples: `'calories'` - `selected` (boolean, optional, reactive) (Only if using selection) Is row selected? Can directly be assigned new Boolean value which changes selection state - `expand` (boolean, optional, reactive) Is row expanded? Can directly be assigned new Boolean value which changes expanded state - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `dense` (boolean, optional) Dense mode; occupies less space - `#top-row` Slot to define how top extra row looks like Scope: - `cols` (object, optional) Column definitions - `#bottom-row` Slot to define how bottom extra row looks like Scope: - `cols` (object, optional) Column definitions - `#footer` Slot to define the table footer (gets rendered in a element); not applied when in 'grid' mode; example: a totals row (which can be made sticky through CSS) Scope: - `cols` (object, optional) Column definitions - `#top` Slot to define how table top looks like Scope: - `pagination` (object, optional) Pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `pagesNumber` (number, optional) Number of pages available - `isFirstPage` (boolean, optional) Are we on first page? - `isLastPage` (boolean, optional) Are we on last page? - `firstPage` (Function, optional) Navigates to first page - `prevPage` (Function, optional) Navigates to previous page, if available - `nextPage` (Function, optional) Navigates to next page, if available - `lastPage` (Function, optional) Navigates to last page - `inFullscreen` (boolean, optional) Is table in fullscreen mode? - `toggleFullscreen` (Function, optional) Toggles fullscreen mode - `#bottom` Slot to define how table bottom looks like Scope: - `pagination` (object, optional) Pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `pagesNumber` (number, optional) Number of pages available - `isFirstPage` (boolean, optional) Are we on first page? - `isLastPage` (boolean, optional) Are we on last page? - `firstPage` (Function, optional) Navigates to first page - `prevPage` (Function, optional) Navigates to previous page, if available - `nextPage` (Function, optional) Navigates to next page, if available - `lastPage` (Function, optional) Navigates to last page - `inFullscreen` (boolean, optional) Is table in fullscreen mode? - `toggleFullscreen` (Function, optional) Toggles fullscreen mode - `#pagination` Slot to override default pagination label and buttons Scope: - `pagination` (object, optional) Pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `pagesNumber` (number, optional) Number of pages available - `isFirstPage` (boolean, optional) Are we on first page? - `isLastPage` (boolean, optional) Are we on last page? - `firstPage` (Function, optional) Navigates to first page - `prevPage` (Function, optional) Navigates to previous page, if available - `nextPage` (Function, optional) Navigates to next page, if available - `lastPage` (Function, optional) Navigates to last page - `inFullscreen` (boolean, optional) Is table in fullscreen mode? - `toggleFullscreen` (Function, optional) Toggles fullscreen mode - `#top-left` Slot to define how left part of the table top looks like Scope: - `pagination` (object, optional) Pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `pagesNumber` (number, optional) Number of pages available - `isFirstPage` (boolean, optional) Are we on first page? - `isLastPage` (boolean, optional) Are we on last page? - `firstPage` (Function, optional) Navigates to first page - `prevPage` (Function, optional) Navigates to previous page, if available - `nextPage` (Function, optional) Navigates to next page, if available - `lastPage` (Function, optional) Navigates to last page - `inFullscreen` (boolean, optional) Is table in fullscreen mode? - `toggleFullscreen` (Function, optional) Toggles fullscreen mode - `#top-right` Slot to define how right part of the table top looks like Scope: - `pagination` (object, optional) Pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `pagesNumber` (number, optional) Number of pages available - `isFirstPage` (boolean, optional) Are we on first page? - `isLastPage` (boolean, optional) Are we on last page? - `firstPage` (Function, optional) Navigates to first page - `prevPage` (Function, optional) Navigates to previous page, if available - `nextPage` (Function, optional) Navigates to next page, if available - `lastPage` (Function, optional) Navigates to last page - `inFullscreen` (boolean, optional) Is table in fullscreen mode? - `toggleFullscreen` (Function, optional) Toggles fullscreen mode - `#top-selection` Slot to define how top table section looks like when user has selected at least one row Scope: - `pagination` (object, optional) Pagination object Object shape: - `sortBy` (string, required) Column name (from column definition) Examples: `'calories'` - `descending` (boolean, required) Is sorting in descending order? - `page` (number, required) Page number (1-based) - `rowsPerPage` (number, required) How many rows per page? 0 means Infinite - `rowsNumber` (number, optional) For server-side fetching only. How many total database rows are there to be added to the table. - `pagesNumber` (number, optional) Number of pages available - `isFirstPage` (boolean, optional) Are we on first page? - `isLastPage` (boolean, optional) Are we on last page? - `firstPage` (Function, optional) Navigates to first page - `prevPage` (Function, optional) Navigates to previous page, if available - `nextPage` (Function, optional) Navigates to next page, if available - `lastPage` (Function, optional) Navigates to last page - `inFullscreen` (boolean, optional) Is table in fullscreen mode? - `toggleFullscreen` (Function, optional) Toggles fullscreen mode - `#no-data` Slot to define how the bottom will look like when is nothing to display Scope: - `message` (string, optional) The suggested message Examples: `'No data available'` - `icon` (string, optional) The suggested icon name (following Quasar convention) Examples: `'warning'` - `filter` (string | object, optional) String/Object to filter table with (the 'filter' prop) ## QTh API ### Props - `props` (object, optional) QTable's header column scoped slot property Examples: `:props="props"` - `col-name` (string, optional) *(added v2.27)* The 'name' of the column this header cell belongs to; Overrides relying on the Vue 'key' attribute, which cannot cross a wrapper component; Only meaningful when used in QTable's 'header' slot Examples: `col-name="desc"` - `auto-width` (boolean, optional) Tries to shrink header column width size; Useful for columns with a checkbox/radio/toggle ### Slots - `#default` Default slot in the devland unslotted content of the component ## QTr API ### Props - `props` (object, optional) QTable's row scoped slot property Examples: `:props="props"` - `no-hover` (boolean, optional) Disable hover effect ### Slots - `#default` Default slot in the devland unslotted content of the component ## QTd API ### Props - `props` (object, optional) QTable's column scoped slot property Examples: `:props="props"` - `col-name` (string, optional) *(added v2.27)* The 'name' of the column this cell belongs to; Overrides relying on the Vue 'key' attribute, which cannot cross a wrapper component; Only meaningful when used in QTable's 'body' slot Examples: `col-name="desc"` - `auto-width` (boolean, optional) Tries to shrink column width size; Useful for columns with a checkbox/radio/toggle - `no-hover` (boolean, optional) Disable hover effect ### Slots - `#default` Default slot in the devland unslotted content of the component ## 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**. ```js 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', // (optional) shrink both th and td to the minimum width // required by their content autoWidth: true }, { 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 Example "Basic": ```vue ``` Example "Force dark mode": ```vue ``` Example "Dense": ```vue ``` > [!TIP] > You can use the `dense` prop along with `$q.screen` to create a responsive behavior. Example: `:dense="$q.screen.lt.md"`. More info: [Screen Plugin](../options/screen-plugin.md). ## 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: Example "Infering columns from data": ```vue ``` ## Sticky header/column > [!WARNING] > Sticky headers and columns are achieved through CSS with `position: sticky`. This is NOT supported on all browsers. Check [caniuse.com](https://caniuse.com/#search=sticky) before using this technique. > [!NOTE] > Pay attention to the code in the "style" section in the following examples, especially around `position: sticky`. > > The browser paints each sticky cell independently and table cells can have fractional sizes, so on some display scalings or browser zoom levels (Windows 125% scaling, for example) hairline gaps can appear between sticky cells, revealing the content scrolled behind them. The 1px `box-shadow` in the same color as the cell background that you will see in the examples below covers such gaps. Example "Sticky header": ```vue ``` The `footer` slot (rendered as a real `` element) can be made sticky the same way. A good use case for it is a totals row: Example "Sticky footer (v2.26+)": ```vue ``` Example "Sticky first column": ```vue ``` Example "Sticky last column": ```vue ``` Example "Sticky header and column": ```vue ``` Example "Sticky header and last column": ```vue ``` ## Separators ```vue ``` ## Styling Example "Custom column": ```vue ``` > [!NOTE] > For all the styling component properties, please check the API card at the top of the page. Example "Custom coloring": ```vue ``` Example "No header/footer": ```vue ``` ## 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). Example "Basic virtual scroll": ```vue ``` You can dynamically load new rows when scroll reaches the end: Example "Dynamic loading virtual scroll": ```vue ``` You can have both virtual scroll and pagination: Example "Virtual scroll and pagination": ```vue ``` 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. Example "Virtual scroll with sticky header": ```vue ``` 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). Example "Virtual scroll with sticky header and column": ```vue ``` 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. Example "Virtual scroll with multiple rows for a data row": ```vue ``` > [!IMPORTANT] > When rendering more than one `QTr` for the same row of data (through the `body` slot), give each `QTr` a distinct `key` and add the `q-virtual-scroll--with-prev` class to every extra `QTr` after the first one. This tells VirtualScroll to group their sizes together with the previous element, so the total height of the data row is measured correctly. If a row should not be measured at all (for example, a separator), use `q-virtual-scroll--skip` instead. This is especially important when also using a sticky header or row expansion, otherwise you may notice an incorrect scroll height or a jumping scroll position. ## Selection > [!IMPORTANT] > The property `row-key` must be set in order for selection to work properly. Example "Single selection": ```vue ``` Example "Multiple selection": ```vue ``` Example "Selection cell slots": ```vue ``` Example "Selection cell slots with range selection": ```vue ``` Example "Custom multiple selection": ```vue ``` ## Visible columns, custom top, fullscreen Please note that columns marked as `required` (in the column definition) cannot be toggled and are always visible. Example "Visible columns, custom top and fullscreen": ```vue ``` Example "Visible columns": ```vue ``` ## Popup editing > [!IMPORTANT] > Below is an example with the user being able to edit “in place” with the help of **QPopupEdit** component. Please note that we are using the `body` scoped slot. **QPopupEdit** won’t work with cell scoped slots. > > QPopupEdit edits one cell at a time. To edit a whole row at once, or to offer per row actions (like Edit and Remove), render your own buttons in a `body-cell` scoped slot and open a [QDialog](dialog.md) holding a form for that row. ```vue ``` ## Editing with an input Example "Input editing": ```vue ``` ## Grid style > [!TIP] > You can use the `grid` prop along with `$q.screen` to create a responsive behavior. Example: `:grid="$q.screen.lt.md"`. More info: [Screen Plugin](../options/screen-plugin.md). In the example below, we let QTable deal with displaying the grid mode (not using the specific slot): ```vue ``` Example "Grid with header": ```vue ``` Example "Colored grid style": ```vue ``` Example "Masonry like grid": ```vue ``` 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. Example "Grid style with slot": ```vue ``` ## Expanding rows > [!IMPORTANT] > Add unique (distinct) `key` on QTr if you generate more than one QTr from a row in data. Example "Internal expansion model": ```vue ``` An external expansion model can also be used: Example "External expansion model": ```vue ``` 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. Example "Virtual scroll with expansion model": ```vue ``` > [!IMPORTANT] > An expanded row is just another `QTr` rendered for the same row of data, so the same rules from "Virtual scrolling" apply: give it its own unique `key` and the `q-virtual-scroll--with-prev` class, so its height is added to the main row when VirtualScroll calculates sizes — even while it's hidden with `v-show`. ## 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 `` element (which, for example, can be made sticky through CSS; see the "Sticky footer" example above). Example "Before/After slots (header/footer)": ```vue ``` ## Pagination > [!NOTE] > When `pagination` has a property named `rowsNumber`, then this means that you’ll be configuring Table for **server**-side pagination (& sorting & filtering). See *"Server side pagination, filter and sorting"* section. Below are two examples of handling the pagination (and sorting and rows per page). The first example highlights how to configure the initial pagination: Example "Initial pagination": ```vue ``` 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. Example "Synchronized pagination": ```vue ``` ## 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. ```vue ``` ## Loading state Example "Default loading": ```vue ``` Example "Custom loading state": ```vue ``` ## Custom top Example "Custom top with add/remove row": ```vue ``` ## Body slots The example below shows how you can use a slot to customize the entire row: Example "Body slot": ```vue ``` > [!IMPORTANT] > When used in the `body` slot, each QTd needs to know which column it belongs to. Set its `col-name` prop (v2.27+) to the column's `name` from the `columns` definition, as in the example above. The Vue `key` attribute is also supported for backwards compatibility, but since `key` is a reserved attribute Vue does not pass it along through `$attrs`, so it cannot be used when wrapping QTd inside a custom component. The same applies to QTh in the `header` slot. Below, we use a slot which gets applied to each body cell: Example "Body-cell slot": ```vue ``` 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. Example "Body-cell-[name] slot": ```vue ``` ## Header slots The example below shows how you can use a slot to customize the entire header row: Example "Header slot": ```vue ``` Below, we use a slot which gets applied to each header cell: Example "Header-cell slot": ```vue ``` 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. Example "Header-cell-[name] slot": ```vue ``` ## No data Example "No Data Label": ```vue ``` 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. Example "No Data Slot": ```vue ``` ## 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: Example "Hiding bottom layer": ```vue ``` ## Custom sorting ```vue ``` ## 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](../options/screen-plugin.md). 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. Example "Using dense prop": ```vue ``` Example "Using grid prop": ```vue ``` ## 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. > [!NOTE] > In the example below, steps have been taken to emulate an ajax call to a server. While the concepts are similar, if you use this code you will need to make the appropriate changes to connect to your own data source. Example "Synchronizing with server": ```vue ``` ## Exporting data Below is an example of a naive csv encoding and then exporting table data by using the [exportFile](../quasar-utils/other-utils.md#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](https://csv.js.org/parse/) and [csv-stringify](https://csv.js.org/stringify/) packages. > [!TIP] > You could also make use of the `filteredSortedRows` internal computed property of QTable should you want to export the user filtered + sorted data. Example "Export to csv": ```vue ``` ## Accessibility *(v2.25+)* QTable renders a native `
` with `thead`/`tbody`, so the tabular semantics come for free. Sortable column headers are focusable, sort on Enter or Space and expose [`aria-sort`](https://www.w3.org/TR/wai-aria-1.2/#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](../options/quasar-language-packs.md). 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](#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 `
` — 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. ```vue ```