Server : Apache System : Linux server2.corals.io 4.18.0-348.2.1.el8_5.x86_64 #1 SMP Mon Nov 15 09:17:08 EST 2021 x86_64 User : corals ( 1002) PHP Version : 7.4.33 Disable Function : exec,passthru,shell_exec,system Directory : /home/corals/vreg/node_modules/bootstrap-vue/src/components/table/ |
# Tables
> For displaying tabular data, `<b-table>` supports pagination, filtering, sorting, custom
> rendering, various style options, events, and asynchronous data. For simple display of tabular
> data without all the fancy features, BootstrapVue provides two lightweight alternative components
> [`<b-table-lite>`](#light-weight-tables) and [`<b-table-simple>`](#simple-tables).
**Example: Basic usage**
```html
<template>
<div>
<b-table striped hover :items="items"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{ age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ age: 89, first_name: 'Geneva', last_name: 'Wilson' },
{ age: 38, first_name: 'Jami', last_name: 'Carney' }
]
}
}
}
</script>
<!-- b-table.vue -->
```
## Items (record data)
`items` is the table data in array format, where each record (row) data are keyed objects. Example
format:
<!-- eslint-disable no-unused-vars -->
```js
const items = [
{ age: 32, first_name: 'Cyndi' },
{ age: 27, first_name: 'Havij' },
{ age: 42, first_name: 'Robert' }
]
```
`<b-table>` automatically samples the first row to extract field names (the keys in the record
data). Field names are automatically "humanized" by converting `kebab-case`, `snake_case`, and
`camelCase` to individual words and capitalizes each word. Example conversions:
- `first_name` becomes `First Name`
- `last-name` becomes `Last Name`
- `age` becomes `Age`
- `YEAR` remains `YEAR`
- `isActive` becomes `Is Active`
These titles will be displayed in the table header, in the order they appear in the **first** record
of data. See the [Fields](#fields-column-definitions) section below for customizing how field
headings appear.
**Note:** Field order is not guaranteed. Fields will typically appear in the order they were defined
in the first row, but this may not always be the case depending on the version of browser in use.
See section [Fields (column definitions)](#fields-column-definitions) below to see how to guarantee
the order of fields, and to override the headings generated.
Record data may also have additional special reserved name keys for colorizing rows and individual
cells (variants), and for triggering additional row detail. The supported optional item record
modifier properties (make sure your field keys do not conflict with these names):
| Property | Type | Description |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_cellVariants` | Object | Bootstrap contextual state applied to individual cells. Keyed by field (See the [Color Variants](/docs/reference/color-variants) for supported values). These variants map to classes `table-${variant}` or `bg-${variant}` (when the `dark` prop is set). |
| `_rowVariant` | String | Bootstrap contextual state applied to the entire row (See the [Color Variants](/docs/reference/color-variants) for supported values). These variants map to classes `table-${variant}` or `bg-${variant}` (when the `dark` prop is set) |
| `_showDetails` | Boolean | Used to trigger the display of the `row-details` scoped slot. See section [Row details support](#row-details-support) below for additional information |
**Example: Using variants for table cells**
```html
<template>
<div>
<b-table hover :items="items"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{ age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{
age: 89,
first_name: 'Geneva',
last_name: 'Wilson',
_rowVariant: 'danger'
},
{
age: 40,
first_name: 'Thor',
last_name: 'MacDonald',
_cellVariants: { age: 'info', first_name: 'warning' }
},
{ age: 29, first_name: 'Dick', last_name: 'Dunlap' }
]
}
}
}
</script>
<!-- b-table-variants.vue -->
```
`items` can also be a reference to a _provider_ function, which returns an `Array` of items data.
Provider functions can also be asynchronous:
- By returning `null` (or `undefined`) and calling a callback, when the data is ready, with the data
array as the only argument to the callback,
- By returning a `Promise` that resolves to an array.
See the ["Using Items Provider functions"](#using-items-provider-functions) section below for more
details.
### Table item notes and warnings
- Avoid manipulating record data in place, as changes to the underlying items data will cause either
the row or entire table to be re-rendered. See [Primary Key](#primary-key), below, for ways to
minimize Vue's re-rendering of rows.
- `items` array records should be a simple object and **must** avoid placing data that may have
circular references in the values within a row. `<b-table>` serializes the row data into strings
for sorting and filtering, and circular references will cause stack overflows to occur and your
app to crash!
## Fields (column definitions)
The `fields` prop is used to customize the table columns headings, and in which order the columns of
data are displayed. The field object keys (i.e. `age` or `first_name` as shown below) are used to
extract the value from each item (record) row, and to provide additional features such as enabling
[sorting](#sorting) on the column, etc.
Fields can be provided as a _simple array_ or an _array of objects_. **Internally the fields data
will be normalized into the _array of objects_ format**. Events or slots that include the column
`field` data will be in the normalized field object format (array of objects for `fields`, or an
object for an individual `field`).
### Fields as a simple array
Fields can be a simple array, for defining the order of the columns, and which columns to display:
**Example: Using `array` fields definition**
```html
<template>
<div>
<b-table striped hover :items="items" :fields="fields"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
// Note `isActive` is left out and will not appear in the rendered table
fields: ['first_name', 'last_name', 'age'],
items: [
{ isActive: true, age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ isActive: false, age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ isActive: false, age: 89, first_name: 'Geneva', last_name: 'Wilson' },
{ isActive: true, age: 38, first_name: 'Jami', last_name: 'Carney' }
]
}
}
}
</script>
<!-- b-table-fields-array.vue -->
```
### Fields as an array of objects
Fields can be a an array of objects, providing additional control over the fields (such as sorting,
formatting, etc.). Only columns (keys) that appear in the fields array will be shown:
**Example: Using array of objects fields definition**
```html
<template>
<div>
<b-table striped hover :items="items" :fields="fields"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
// Note 'isActive' is left out and will not appear in the rendered table
fields: [
{
key: 'last_name',
sortable: true
},
{
key: 'first_name',
sortable: false
},
{
key: 'age',
label: 'Person age',
sortable: true,
// Variant applies to the whole column, including the header and footer
variant: 'danger'
}
],
items: [
{ isActive: true, age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ isActive: false, age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ isActive: false, age: 89, first_name: 'Geneva', last_name: 'Wilson' },
{ isActive: true, age: 38, first_name: 'Jami', last_name: 'Carney' }
]
}
}
}
</script>
<!-- b-table-fields-array-of-objects.vue -->
```
### Field definition reference
The following field properties are recognized:
| Property | Type | Description |
| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | String | The key for selecting data from the record in the items array. Required when setting the `fields` via an array of objects. The `key` is also used for generating the [custom data rendering](#custom-data-rendering) and [custom header and footer](#header-and-footer-custom-rendering-via-scoped-slots) slot names. |
| `label` | String | Appears in the columns table header (and footer if `foot-clone` is set). Defaults to the field's key (in humanized format) if not provided. It's possible to use empty labels by assigning an empty string `""` but be sure you also set `headerTitle` to provide non-sighted users a hint about the column contents. |
| `headerTitle` | String | Text to place on the fields header `<th>` attribute `title`. Defaults to no `title` attribute. |
| `headerAbbr` | String | Text to place on the fields header `<th>` attribute `abbr`. Set this to the unabbreviated version of the label (or title) if label (or title) is an abbreviation. Defaults to no `abbr` attribute. |
| `class` | String or Array | Class name (or array of class names) to add to `<th>` **and** `<td>` in the column. |
| `formatter` | String or Function | A formatter callback function or name of a method in your component, can be used instead of (or in conjunction with) scoped field slots. The formatter will be called with the syntax `formatter(value, key, item)`. Refer to [Custom Data Rendering](#custom-data-rendering) for more details. |
| `sortable` | Boolean | Enable sorting on this column. Refer to the [Sorting](#sorting) Section for more details. |
| `sortKey` | String | <span class="badge badge-secondary">v2.17.0+</span> Set the value of `sortBy` for the column in the emitted context when `no-local-sorting` is `true`. |
| `sortDirection` | String | Set the initial sort direction on this column when it becomes sorted. Refer to the [Change initial sort direction](#change-initial-sort-direction) Section for more details. |
| `sortByFormatted` | Boolean or Function | Sort the column by the result of the field's `formatter` callback function when set to `true`. Default is `false`. Boolean has no effect if the field does not have a `formatter`. Optionally accepts a formatter function _reference_ to format the value for sorting purposes only. Refer to the [Sorting](#sorting) Section for more details. |
| `filterByFormatted` | Boolean or Function | Filter the column by the result of the field's `formatter` callback function when set to `true`. Default is `false`. Boolean has no effect if the field does not have a `formatter`. Optionally accepts a formatter function _reference_ to format the value for filtering purposes only. Refer to the [Filtering](#filtering) section for more details. |
| `tdClass` | String or Array or Function | Class name (or array of class names) to add to `<tbody>` data `<td>` cells in the column. If custom classes per cell are required, a callback function can be specified instead. The function will be called as `tdClass(value, key, item)` and it must return an `Array` or `String`. |
| `thClass` | String or Array | Class name (or array of class names) to add to this field's `<thead>`/`<tfoot>` heading `<th>` cell. |
| `thStyle` | Object | JavaScript object representing CSS styles you would like to apply to the table `<thead>`/`<tfoot>` field `<th>`. |
| `variant` | String | Apply contextual class to all the `<th>` **and** `<td>` in the column - `active`, `success`, `info`, `warning`, `danger`. These variants map to classes `thead-${variant}` (in the header), `table-${variant}` (in the body), or `bg-${variant}` (when the prop `dark` is set). |
| `tdAttr` | Object or Function | JavaScript object representing additional attributes to apply to the `<tbody>` field `<td>` cell. If custom attributes per cell are required, a callback function can be specified instead. The function will be called as `tdAttr(value, key, item)` and it must return an `Object`. |
| `thAttr` | Object or Function | JavaScript object representing additional attributes to apply to the field's `<thead>`/`<tfoot>` heading `<th>` cell. If the field's `isRowHeader` is set to `true`, the attributes will also apply to the `<tbody>` field `<th>` cell. If custom attributes per cell are required, a callback function can be specified instead. The function will be called as `thAttr(value, key, item, type)` and it must return an `Object`. |
| `isRowHeader` | Boolean | When set to `true`, the field's item data cell will be rendered with `<th>` rather than the default of `<td>`. |
| `stickyColumn` | Boolean | When set to `true`, and the table in [responsive](#responsive-tables) mode or has [sticky headers](#sticky-headers), will cause the column to become fixed to the left when the table's horizontal scrollbar is scrolled. See [Sticky columns](#sticky-columns) for more details |
**Notes:**
- Field properties, if not present, default to `null` (falsey) unless otherwise stated above.
- `class`, `thClass`, `tdClass` etc. will not work with classes that are defined in scoped CSS,
unless you are using VueLoader's
[Deep selector](https://vue-loader.vuejs.org/guide/scoped-css.html#child-component-root-elements).
- For information on the syntax supported by `thStyle`, see
[Class and Style Bindings](https://vuejs.org/v2/guide/class-and-style.html#Binding-Inline-Styles)
in the Vue.js guide.
- Any additional properties added to the field definition objects will be left intact - so you can
access them via the named scoped slots for custom data, header, and footer rendering.
For information and usage about scoped slots and formatters, refer to the
[Custom Data Rendering](#custom-data-rendering) section below.
Feel free to mix and match simple array and object array together:
<!-- eslint-disable no-unused-vars -->
```js
const fields = [
{ key: 'first_name', label: 'First' },
{ key: 'last_name', label: 'Last' },
'age',
'sex'
]
```
## Primary key
`<b-table>` provides an additional prop `primary-key`, which you can use to identify the _name_ of
the field key that _uniquely_ identifies the row.
The value specified by the primary column key **must be** either a `string` or `number`, and **must
be unique** across all rows in the table.
The primary key column does not need to appear in the displayed fields.
### Table row ID generation
When provided, the `primary-key` will generate a unique ID for each item row `<tr>` element. The ID
will be in the format of `{table-id}__row_{primary-key-value}`, where `{table-id}` is the unique ID
of the `<b-table>` and `{primary-key-value}` is the value of the item's field value for the field
specified by `primary-key`.
### Table render and transition optimization
The `primary-key` is also used by `<b-table>` to help Vue optimize the rendering of table rows.
Internally, the value of the field key specified by the `primary-key` prop is used as the Vue `:key`
value for each rendered item row `<tr>` element.
If you are seeing rendering issue (i.e. tooltips hiding or unexpected subcomponent re-usage when
item data changes or data is sorted/filtered/edited) or table row transitions are not working,
setting the `primary-key` prop (if you have a unique identifier per row) can alleviate these issues.
Specifying the `primary-key` column is handy if you are using 3rd party table transitions or drag
and drop plugins, as they rely on having a consistent and unique per row `:key` value.
If `primary-key` is not provided, `<b-table>` will auto-generate keys based on the displayed row's
index number (i.e. position in the _displayed_ table rows). This may cause GUI issues such as sub
components/elements that are rendering with previous results (i.e. being re-used by Vue's render
patch optimization routines). Specifying a `primary-key` column can alleviate this issue (or you can
place a unique `:key` on your element/components in your custom formatted field slots).
Refer to the [Table body transition support](#table-body-transition-support) section for additional
details.
## Table style options
### Table styling
`<b-table>` provides several props to alter the style of the table:
| prop | Type | Description |
| -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `striped` | Boolean | Add zebra-striping to the table rows within the `<tbody>` |
| `bordered` | Boolean | For borders on all sides of the table and cells. |
| `borderless` | Boolean | removes inner borders from table. |
| `outlined` | Boolean | For a thin border on all sides of the table. Has no effect if `bordered` is set. |
| `small` | Boolean | To make tables more compact by cutting cell padding in half. |
| `hover` | Boolean | To enable a hover highlighting state on table rows within a `<tbody>` |
| `dark` | Boolean | Invert the colors — with light text on dark backgrounds (equivalent to Bootstrap v4 class `.table-dark`) |
| `fixed` | Boolean | Generate a table with equal fixed-width columns (`table-layout: fixed;`) |
| `responsive` | Boolean or String | Generate a responsive table to make it scroll horizontally. Set to `true` for an always responsive table, or set it to one of the breakpoints `'sm'`, `'md'`, `'lg'`, or `'xl'` to make the table responsive (horizontally scroll) only on screens smaller than the breakpoint. See [Responsive tables](#responsive-tables) below for details. |
| `sticky-header` | Boolean or String | Generates a vertically scrollable table with sticky headers. Set to `true` to enable sticky headers (default table max-height of `300px`), or set it to a string containing a height (with CSS units) to specify a maximum height other than `300px`. See the [Sticky header](#sticky-headers) section below for details. |
| `stacked` | Boolean or String | Generate a responsive stacked table. Set to `true` for an always stacked table, or set it to one of the breakpoints `'sm'`, `'md'`, `'lg'`, or `'xl'` to make the table visually stacked only on screens smaller than the breakpoint. See [Stacked tables](#stacked-tables) below for details. |
| `caption-top` | Boolean | If the table has a caption, and this prop is set to `true`, the caption will be visually placed above the table. If `false` (the default), the caption will be visually placed below the table. |
| `table-variant` | String | Give the table an overall theme color variant. |
| `head-variant` | String | Use `'light'` or `'dark'` to make table header appear light or dark gray, respectively |
| `foot-variant` | String | Use `'light'` or `'dark'` to make table footer appear light or dark gray, respectively. If not set, `head-variant` will be used. Has no effect if `foot-clone` is not set |
| `foot-clone` | Boolean | Turns on the table footer, and defaults with the same contents a the table header |
| `no-footer-sorting` | Boolean | When `foot-clone` is true and the table is sortable, disables the sorting icons and click behaviour on the footer heading cells. Refer to the [Sorting](#sorting) section below for more details. |
| `no-border-collapse` | Boolean | Disables the default of collapsing of the table borders. Mainly for use with [sticky headers](#sticky-headers) and/or [sticky columns](#sticky-columns). Will cause the appearance of double borders in some situations. |
**Note:** The table style options `fixed`, `stacked`, `caption-top`, `no-border-collapse`, sticky
headers, sticky columns and the table sorting feature, all require BootstrapVue's custom CSS.
**Example: Basic table styles**
```html
<template>
<div>
<b-form-group label="Table Options" label-cols-lg="2" v-slot="{ ariaDescribedby }">
<b-form-checkbox v-model="striped" :aria-describedby="ariaDescribedby" inline>Striped</b-form-checkbox>
<b-form-checkbox v-model="bordered" :aria-describedby="ariaDescribedby" inline>Bordered</b-form-checkbox>
<b-form-checkbox v-model="borderless" :aria-describedby="ariaDescribedby" inline>Borderless</b-form-checkbox>
<b-form-checkbox v-model="outlined" :aria-describedby="ariaDescribedby" inline>Outlined</b-form-checkbox>
<b-form-checkbox v-model="small" :aria-describedby="ariaDescribedby" inline>Small</b-form-checkbox>
<b-form-checkbox v-model="hover" :aria-describedby="ariaDescribedby" inline>Hover</b-form-checkbox>
<b-form-checkbox v-model="dark" :aria-describedby="ariaDescribedby" inline>Dark</b-form-checkbox>
<b-form-checkbox v-model="fixed" :aria-describedby="ariaDescribedby" inline>Fixed</b-form-checkbox>
<b-form-checkbox v-model="footClone" :aria-describedby="ariaDescribedby" inline>Foot Clone</b-form-checkbox>
<b-form-checkbox v-model="noCollapse" :aria-describedby="ariaDescribedby" inline>No border collapse</b-form-checkbox>
</b-form-group>
<b-form-group label="Head Variant" label-cols-lg="2" v-slot="{ ariaDescribedby }">
<b-form-radio-group
v-model="headVariant"
:aria-describedby="ariaDescribedby"
class="mt-lg-2"
>
<b-form-radio :value="null" inline>None</b-form-radio>
<b-form-radio value="light" inline>Light</b-form-radio>
<b-form-radio value="dark" inline>Dark</b-form-radio>
</b-form-radio-group>
</b-form-group>
<b-form-group label="Table Variant" label-for="table-style-variant" label-cols-lg="2">
<b-form-select
id="table-style-variant"
v-model="tableVariant"
:options="tableVariants"
>
<template #first>
<option value="">-- None --</option>
</template>
</b-form-select>
</b-form-group>
<b-table
:striped="striped"
:bordered="bordered"
:borderless="borderless"
:outlined="outlined"
:small="small"
:hover="hover"
:dark="dark"
:fixed="fixed"
:foot-clone="footClone"
:no-border-collapse="noCollapse"
:items="items"
:fields="fields"
:head-variant="headVariant"
:table-variant="tableVariant"
></b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: ['first_name', 'last_name', 'age'],
items: [
{ age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ age: 89, first_name: 'Geneva', last_name: 'Wilson' }
],
tableVariants: [
'primary',
'secondary',
'info',
'danger',
'warning',
'success',
'light',
'dark'
],
striped: false,
bordered: false,
borderless: false,
outlined: false,
small: false,
hover: false,
dark: false,
fixed: false,
footClone: false,
headVariant: null,
tableVariant: '',
noCollapse: false
}
}
}
</script>
<!-- b-table-bordered.vue -->
```
### Row styling and attributes
You can also style every row using the `tbody-tr-class` prop, and optionally supply additional
attributes via the `tbody-tr-attr` prop:
| Property | Type | Description |
| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tbody-tr-class` | String, Array or Function | Classes to be applied to every row on the table. If a function is given, it will be called as `tbodyTrClass( item, type )` and it may return an `Array`, `Object` or `String`. |
| `tbody-tr-attr` | Object or Function | Attributes to be applied to every row on the table. If a function is given, it will be called as `tbodyTrAttr( item, type )` and it must return an `Object`. |
When passing a function reference to `tbody-tr-class` or `tbody-tr-attr`, the function's arguments
will be as follows:
- `item` - The item record data associated with the row. For rows that are not associated with an
item record, this value will be `null` or `undefined`
- `type` - The type of row being rendered. `'row'` for an item row, `'row-details'` for an item
details row, `'row-top'` for the fixed row top slot, `'row-bottom'` for the fixed row bottom slot,
or `'table-busy'` for the table busy slot.
**Example: Basic row styles**
```html
<template>
<div>
<b-table :items="items" :fields="fields" :tbody-tr-class="rowClass"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: ['first_name', 'last_name', 'age'],
items: [
{ age: 40, first_name: 'Dickerson', last_name: 'Macdonald', status: 'awesome' },
{ age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ age: 89, first_name: 'Geneva', last_name: 'Wilson' }
]
}
},
methods: {
rowClass(item, type) {
if (!item || type !== 'row') return
if (item.status === 'awesome') return 'table-success'
}
}
}
</script>
<!-- b-table-styled-row.vue -->
```
### Responsive tables
Responsive tables allow tables to be scrolled horizontally with ease. Make any table responsive
across all viewports by setting the prop `responsive` to `true`. Or, pick a maximum breakpoint with
which to have a responsive table up to by setting the prop `responsive` to one of the breakpoint
values: `sm`, `md`, `lg`, or `xl`.
**Example: Always responsive table**
```html
<template>
<div>
<b-table responsive :items="items"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{
heading1: 'table cell',
heading2: 'table cell',
heading3: 'table cell',
heading4: 'table cell',
heading5: 'table cell',
heading6: 'table cell',
heading7: 'table cell',
heading8: 'table cell',
heading9: 'table cell',
heading10: 'table cell',
heading11: 'table cell',
heading12: 'table cell'
},
{
heading1: 'table cell',
heading2: 'table cell',
heading3: 'table cell',
heading4: 'table cell',
heading5: 'table cell',
heading6: 'table cell',
heading7: 'table cell',
heading8: 'table cell',
heading9: 'table cell',
heading10: 'table cell',
heading11: 'table cell',
heading12: 'table cell'
},
{
heading1: 'table cell',
heading2: 'table cell',
heading3: 'table cell',
heading4: 'table cell',
heading5: 'table cell',
heading6: 'table cell',
heading7: 'table cell',
heading8: 'table cell',
heading9: 'table cell',
heading10: 'table cell',
heading11: 'table cell',
heading12: 'table cell'
}
]
}
}
}
</script>
<!-- b-table-responsive.vue -->
```
**Responsive table notes:**
- _Possible vertical clipping/truncation_. Responsive tables make use of `overflow-y: hidden`, which
clips off any content that goes beyond the bottom or top edges of the table. In particular, this
may clip off dropdown menus and other third-party widgets.
- Using props `responsive` and `fixed` together will **not** work as expected. Fixed table layout
uses the first row (table header in this case) to compute the width required by each column (and
the overall table width) to fit within the width of the parent container — without taking
cells in the `<tbody>` into consideration — resulting in table that may not be responsive.
To get around this limitation, you would need to specify widths for the columns (or certain
columns) via one of the following methods:
- Use `<col>` elements within the [`table-colgroup` slot](#table-colgroup) that have widths set
(e.g. `<col style="width: 20rem">`), or
- Wrap header cells in `<div>` elements, via the use of
[custom header rendering](#header-and-footer-custom-rendering-via-scoped-slots), which have a
minimum width set on them, or
- Use the `thStyle` property of the [field definition object](#field-definition-reference) to set
a width for the column(s), or
- Use custom CSS to define classes to apply to the columns to set widths, via the `thClass` or
`class` properties of the [field definition object](#field-definition-reference).
### Stacked tables
An alternative to responsive tables, BootstrapVue includes the stacked table option (using custom
SCSS/CSS), which allow tables to be rendered in a visually stacked format. Make any table stacked
across _all viewports_ by setting the prop `stacked` to `true`. Or, alternatively, set a breakpoint
at which the table will return to normal table format by setting the prop `stacked` to one of the
breakpoint values `'sm'`, `'md'`, `'lg'`, or `'xl'`.
Column header labels will be rendered to the left of each field value using a CSS `::before` pseudo
element, with a width of 40%.
The `stacked` prop takes precedence over the [`sticky-header`](#sticky-headers) prop and the
[`stickyColumn`](#sticky-columns) field definition property.
**Example: Always stacked table**
```html
<template>
<div>
<b-table stacked :items="items"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{ age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ age: 89, first_name: 'Geneva', last_name: 'Wilson' }
]
}
}
}
</script>
<!-- b-table-stacked.vue -->
```
**Note: When the table is visually stacked:**
- The table header (and table footer) will be hidden.
- Custom rendered header slots will not be shown, rather, the fields' `label` will be used.
- The table **cannot** be sorted by clicking the rendered field labels. You will need to provide an
external control to select the field to sort by and the sort direction. See the
[Sorting](#sorting) section below for sorting control information, as well as the
[complete example](#complete-example) at the bottom of this page for an example of controlling
sorting via the use of form controls.
- The slots `top-row` and `bottom-row` will be hidden when visually stacked.
- The table caption, if provided, will always appear at the top of the table when visually stacked.
- In an always stacked table, the table header and footer, and the fixed top and bottom row slots
will not be rendered.
BootstrapVue's custom CSS is required in order to support stacked tables.
### Table caption
Add an optional caption to your table via the prop `caption` or the named slot `table-caption` (the
slot takes precedence over the prop). The default Bootstrap v4 styling places the caption at the
bottom of the table:
```html
<template>
<div>
<b-table :items="items" :fields="fields">
<template #table-caption>This is a table caption.</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: ['first_name', 'last_name', 'age'],
items: [
{ age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ age: 89, first_name: 'Geneva', last_name: 'Wilson' }
]
}
}
}
</script>
<!-- b-table-caption.vue -->
```
You can have the caption placed at the top of the table by setting the `caption-top` prop to `true`:
```html
<template>
<div>
<b-table :items="items" :fields="fields" caption-top>
<template #table-caption>This is a table caption at the top.</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: ['first_name', 'last_name', 'age'],
items: [
{ age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ age: 89, first_name: 'Geneva', last_name: 'Wilson' }
]
}
}
}
</script>
<!-- b-table-caption-top.vue -->
```
You can also use [custom CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/caption-side) to
control the caption positioning.
### Table colgroup
Use the named slot `table-colgroup` to specify `<colgroup>` and `<col>` elements for optional
grouping and styling of table columns. Note the styles available via `<col>` elements are limited.
Refer to [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/colgroup) for details and
usage of `<colgroup>`
Slot `table-colgroup` can be optionally scoped, receiving an object with the following properties:
| Property | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `columns` | Number | The number of columns in the rendered table |
| `fields` | Array | Array of field definition objects (normalized to the [array of objects](#fields-as-an-array-of-objects) format) |
When provided, the content of the `table-colgroup` slot will be placed _inside_ of a `<colgroup>`
element. there is no need to provide your own outer `<colgroup>` element. When a series of table
columns should be grouped for assistive technology reasons (for conveying logical column
associations, use a `<col span="#">` element (with `#` replaced with the number of grouped columns)
to group the series of columns.
**Tip:** In some situations when trying to set column widths via `style` or `class` on the `<col>`
element, you may find that placing the table in `fixed` header width (table fixed layout mode) mode,
combined with `responsive` (horizontal scrolling) mode will help, although you will need to have
explicit widths, or minimum widths, via a style or a class for each column's respective `<col>`
element. For example:
```html
<b-table fixed responsive :items="items" :fields="fields" ... >
<template #table-colgroup="scope">
<col
v-for="field in scope.fields"
:key="field.key"
:style="{ width: field.key === 'foo' ? '120px' : '180px' }"
>
</template>
<!-- additional table slots here if needed -->
</b-table>
```
### Table busy state
`<b-table>` provides a `busy` prop that will flag the table as busy, which you can set to `true`
just before you update your items, and then set it to `false` once you have your items. When in the
busy state, the table will have the attribute `aria-busy="true"`.
During the busy state, the table will be rendered in a "muted" look (`opacity: 0.6`), using the
following custom CSS:
```css
/* Busy table styling */
table.b-table[aria-busy='true'] {
opacity: 0.6;
}
```
You can override this styling using your own CSS.
You may optionally provide a `table-busy` slot to show a custom loading message or spinner whenever
the table's busy state is `true`. The slot will be placed in a `<tr>` element with class
`b-table-busy-slot`, which has one single `<td>` with a `colspan` set to the number of fields.
**Example of `table-busy` slot usage:**
```html
<template>
<div>
<b-button @click="toggleBusy">Toggle Busy State</b-button>
<b-table :items="items" :busy="isBusy" class="mt-3" outlined>
<template #table-busy>
<div class="text-center text-danger my-2">
<b-spinner class="align-middle"></b-spinner>
<strong>Loading...</strong>
</div>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
isBusy: false,
items: [
{ first_name: 'Dickerson', last_name: 'MacDonald', age: 40 },
{ first_name: 'Larsen', last_name: 'Shaw', age: 21 },
{ first_name: 'Geneva', last_name: 'Wilson', age: 89 },
{ first_name: 'Jami', last_name: 'Carney', age: 38 }
]
}
},
methods: {
toggleBusy() {
this.isBusy = !this.isBusy
}
}
}
</script>
<!-- b-table-busy-slot.vue -->
```
Also see the [Using Items Provider Functions](#using-items-provider-functions) below for additional
information on the `busy` state.
**Notes:**
- All click related and hover events, and sort-changed events will **not** be emitted when the table
is in the `busy` state.
- Busy styling and slot are not available in the `<b-table-lite>` component.
## Custom data rendering
Custom rendering for each data field in a row is possible using either
[scoped slots](https://vuejs.org/v2/guide/components.html#Scoped-Slots) or a formatter callback
function, or a combination of both.
### Scoped field slots
Scoped field slots give you greater control over how the record data appears. You can use scoped
slots to provided custom rendering for a particular field. If you want to add an extra field which
does not exist in the records, just add it to the [`fields`](#fields-column-definitions) array, and
then reference the field(s) in the scoped slot(s). Scoped field slots use the following naming
syntax: `'cell(' + field key + ')'`.
You can use the default _fall-back_ scoped slot `'cell()'` to format any cells that do not have an
explicit scoped slot provided.
**Example: Custom data rendering with scoped slots**
```html
<template>
<div>
<b-table small :fields="fields" :items="items" responsive="sm">
<!-- A virtual column -->
<template #cell(index)="data">
{{ data.index + 1 }}
</template>
<!-- A custom formatted column -->
<template #cell(name)="data">
<b class="text-info">{{ data.value.last.toUpperCase() }}</b>, <b>{{ data.value.first }}</b>
</template>
<!-- A virtual composite column -->
<template #cell(nameage)="data">
{{ data.item.name.first }} is {{ data.item.age }} years old
</template>
<!-- Optional default data cell scoped slot -->
<template #cell()="data">
<i>{{ data.value }}</i>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: [
// A virtual column that doesn't exist in items
'index',
// A column that needs custom formatting
{ key: 'name', label: 'Full Name' },
// A regular column
'age',
// A regular column
'sex',
// A virtual column made up from two fields
{ key: 'nameage', label: 'First name and age' }
],
items: [
{ name: { first: 'John', last: 'Doe' }, sex: 'Male', age: 42 },
{ name: { first: 'Jane', last: 'Doe' }, sex: 'Female', age: 36 },
{ name: { first: 'Rubin', last: 'Kincade' }, sex: 'Male', age: 73 },
{ name: { first: 'Shirley', last: 'Partridge' }, sex: 'Female', age: 62 }
]
}
}
}
</script>
<!-- b-table-data-slots.vue -->
```
The slot's scope variable (`data` in the above sample) will have the following properties:
| Property | Type | Description |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index` | Number | The row number (indexed from zero) relative to the _displayed_ rows |
| `item` | Object | The entire raw record data (i.e. `items[index]`) for this row (before any formatter is applied) |
| `value` | Any | The value for this key in the record (`null` or `undefined` if a virtual column), or the output of the field's [`formatter` function](#formatter-callback) |
| `unformatted` | Any | The raw value for this key in the item record (`null` or `undefined` if a virtual column), before being passed to the field's [`formatter` function](#formatter-callback) |
| `field` | Object | The field's normalized field definition object |
| `detailsShowing` | Boolean | Will be `true` if the row's `row-details` scoped slot is visible. See section [Row details support](#row-details-support) below for additional information |
| `toggleDetails` | Function | Can be called to toggle the visibility of the rows `row-details` scoped slot. See section [Row details support](#row-details-support) below for additional information |
| `rowSelected` | Boolean | Will be `true` if the row has been selected. See section [Row select support](#row-select-support) for additional information |
| `selectRow` | Function | When called, selects the current row. See section [Row select support](#row-select-support) for additional information |
| `unselectRow` | Function | When called, unselects the current row. See section [Row select support](#row-select-support) for additional information |
**Notes:**
- `index` will not always be the actual row's index number, as it is computed after filtering,
sorting and pagination have been applied to the original table data. The `index` value will refer
to the **displayed row number**. This number will align with the indexes from the optional
[`v-model` bound](#v-model-binding) variable.
- When using the new Vue 2.6 `v-slot` syntax, note that slot names **cannot** contain spaces, and
when using in-browser DOM templates the slot names will _always_ be lower cased. To get around
this, you can pass the slot name using Vue's
[dynamic slot names](https://vuejs.org/v2/guide/components-slots.html#Dynamic-Slot-Names)
#### Displaying raw HTML
By default `b-table` escapes HTML tags in items data and results of formatter functions, if you need
to display raw HTML code in `b-table`, you should use `v-html` directive on an element in a in
scoped field slot.
```html
<template>
<div>
<b-table :items="items">
<template #cell(html)="data">
<span v-html="data.value"></span>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{
text: 'This is <i>escaped</i> content',
html: 'This is <i>raw <strong>HTML</strong></i> <span style="color:red">content</span>'
}
]
}
}
}
</script>
<!-- b-table-html-data-slots.vue -->
```
<p class="alert alert-danger">
<strong>Warning:</strong> Be cautious of using the <code>v-html</code> method to display user
supplied content, as it may make your application vulnerable to
<a class="alert-link" href="https://en.wikipedia.org/wiki/Cross-site_scripting">
<abbr title="Cross Site Scripting Attacks">XSS attacks</abbr></a>, if you do not first
<a class="alert-link" href="https://en.wikipedia.org/wiki/HTML_sanitization">sanitize</a> the
user supplied string.
</p>
### Formatter callback
Optionally, you can customize field output by using a formatter callback function. To enable this,
the field's `formatter` property is used. The value of this property may be String or function
reference. In case of a String value, the function must be defined at the parent component's
methods. When providing `formatter` as a `Function`, it must be declared at global scope (window or
as global mixin at Vue, or as an anonymous function), unless it has been bound to a `this` context.
The callback function accepts three arguments - `value`, `key`, and `item`, and should return the
formatted value as a string (HTML strings are not supported)
**Example: Custom data rendering with formatter callback function**
```html
<template>
<div>
<b-table :fields="fields" :items="items">
<template #cell(name)="data">
<!-- `data.value` is the value after formatted by the Formatter -->
<a :href="`#${data.value.replace(/[^a-z]+/i,'-').toLowerCase()}`">{{ data.value }}</a>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: [
{
// A column that needs custom formatting,
// calling formatter 'fullName' in this app
key: 'name',
label: 'Full Name',
formatter: 'fullName'
},
// A regular column
'age',
{
// A regular column with custom formatter
key: 'sex',
formatter: value => {
return value.charAt(0).toUpperCase()
}
},
{
// A virtual column with custom formatter
key: 'birthYear',
label: 'Calculated Birth Year',
formatter: (value, key, item) => {
return new Date().getFullYear() - item.age
}
}
],
items: [
{ name: { first: 'John', last: 'Doe' }, sex: 'Male', age: 42 },
{ name: { first: 'Jane', last: 'Doe' }, sex: 'Female', age: 36 },
{ name: { first: 'Rubin', last: 'Kincade' }, sex: 'male', age: 73 },
{ name: { first: 'Shirley', last: 'Partridge' }, sex: 'female', age: 62 }
]
}
},
methods: {
fullName(value) {
return `${value.first} ${value.last}`
}
}
}
</script>
<!-- b-table-data-formatter.vue -->
```
## Header and Footer custom rendering via scoped slots
It is also possible to provide custom rendering for the tables `thead` and `tfoot` elements. Note by
default the table footer is not rendered unless `foot-clone` is set to `true`.
Scoped slots for the header and footer cells uses a special naming convention of
`'head(<fieldkey>)'` and `'foot(<fieldkey>)'` respectively. if a `'foot(...)'` slot for a field is
not provided, but a `'head(...)'` slot is provided, then the footer will use the `'head(...)'` slot
content.
You can use a default _fall-back_ scoped slot `'head()'` or `'foot()'` to format any header or
footer cells that do not have an explicit scoped slot provided.
```html
<template>
<div>
<b-table :fields="fields" :items="items" foot-clone>
<!-- A custom formatted data column cell -->
<template #cell(name)="data">
{{ data.value.first }} {{ data.value.last }}
</template>
<!-- A custom formatted header cell for field 'name' -->
<template #head(name)="data">
<span class="text-info">{{ data.label.toUpperCase() }}</span>
</template>
<!-- A custom formatted footer cell for field 'name' -->
<template #foot(name)="data">
<span class="text-danger">{{ data.label }}</span>
</template>
<!-- Default fall-back custom formatted footer cell -->
<template #foot()="data">
<i>{{ data.label }}</i>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: [
// A column that needs custom formatting
{ key: 'name', label: 'Full Name' },
// A regular column
'age',
// A regular column
'sex'
],
items: [
{ name: { first: 'John', last: 'Doe' }, sex: 'Male', age: 42 },
{ name: { first: 'Jane', last: 'Doe' }, sex: 'Female', age: 36 },
{ name: { first: 'Rubin', last: 'Kincade' }, sex: 'Male', age: 73 },
{ name: { first: 'Shirley', last: 'Partridge' }, sex: 'Female', age: 62 }
]
}
}
}
</script>
<!-- b-table-head-foot-slots.vue -->
```
The slots can be optionally scoped (`data` in the above example), and will have the following
properties:
| Property | Type | Description |
| --------------- | ------ | ----------------------------------------------------------------------------------------- |
| `column` | String | The fields's `key` value |
| `field` | Object | the field's object (from the `fields` prop) |
| `label` | String | The fields label value (also available as `data.field.label`) |
| `selectAllRows` | Method | Select all rows (applicable if the table is in [`selectable`](#row-select-support) mode |
| `clearSelected` | Method | Unselect all rows (applicable if the table is in [`selectable`](#row-select-support) mode |
When placing inputs, buttons, selects or links within a `head(...)` or `foot(...)` slot, note that
`head-clicked` event will not be emitted when the input, select, textarea is clicked (unless they
are disabled). `head-clicked` will never be emitted when clicking on links or buttons inside the
scoped slots (even when disabled)
**Notes:**
- When using the new Vue 2.6 `v-slot` syntax, note that slot names **cannot** contain spaces, and
when using in-browser DOM templates the slot names will _always_ be lower cased. To get around
this, you can pass the slot name using Vue's
[dynamic slot names](https://vuejs.org/v2/guide/components-slots.html#Dynamic-Slot-Names)
### Adding additional rows to the header
If you wish to add additional rows to the header you may do so via the `thead-top` slot. This slot
is inserted before the header cells row, and is not automatically encapsulated by `<tr>..</tr>`
tags. It is recommended to use the BootstrapVue [table helper components](#table-helper-components),
rather than native browser table child elements.
```html
<template>
<div>
<b-table
:items="items"
:fields="fields"
responsive="sm"
>
<template #thead-top="data">
<b-tr>
<b-th colspan="2"><span class="sr-only">Name and ID</span></b-th>
<b-th variant="secondary">Type 1</b-th>
<b-th variant="primary" colspan="3">Type 2</b-th>
<b-th variant="danger">Type 3</b-th>
</b-tr>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{ name: 'Stephen Hawking', id: 1, type1: false, type2a: true, type2b: false, type2c: false, type3: false },
{ name: 'Johnny Appleseed', id: 2, type1: false, type2a: true, type2b: true, type2c: false, type3: false },
{ name: 'George Washington', id: 3, type1: false, type2a: false, type2b: false, type2c: false, type3: true },
{ name: 'Albert Einstein', id: 4, type1: true, type2a: false, type2b: false, type2c: true, type3: false },
{ name: 'Isaac Newton', id: 5, type1: true, type2a: true, type2b: false, type2c: true, type3: false },
],
fields: [
'name',
{ key: 'id', label: 'ID' },
{ key: 'type1', label: 'Type 1' },
{ key: 'type2a', label: 'Type 2A' },
{ key: 'type2b', label: 'Type 2B' },
{ key: 'type2c', label: 'Type 2C' },
{ key: 'type3', label: 'Type 3' }
]
}
}
}
</script>
<!-- b-table-thead-top-slot.vue -->
```
Slot `thead-top` can be optionally scoped, receiving an object with the following properties:
| Property | Type | Description |
| --------------- | ------ | ----------------------------------------------------------------------------------------- |
| `columns` | Number | The number of columns in the rendered table |
| `fields` | Array | Array of field definition objects (normalized to the array of objects format) |
| `selectAllRows` | Method | Select all rows (applicable if the table is in [`selectable`](#row-select-support) mode |
| `clearSelected` | Method | Unselect all rows (applicable if the table is in [`selectable`](#row-select-support) mode |
### Creating a custom footer
If you need greater layout control of the content of the `<tfoot>`, you can use the optionally
scoped slot `custom-foot` to provide your own rows and cells. Use BootstrapVue's
[table helper sub-components](#table-helper-components) `<b-tr>`, `<b-th>`, and `<b-td>` to generate
your custom footer layout.
Slot `custom-foot` can be optionally scoped, receiving an object with the following properties:
| Property | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------ |
| `columns` | Number | The number of columns in the rendered table |
| `fields` | Array | Array of field definition objects (normalized to the array of objects format) |
| `items` | Array | Array of the currently _displayed_ items records - after filtering, sorting and pagination |
**Notes:**
- The `custom-foot` slot will **not** be rendered if the `foot-clone` prop has been set.
- `head-clicked` events are not be emitted when clicking on `custom-foot` cells.
- Sorting and sorting icons are not available for cells in the `custom-foot` slot.
- The custom footer will not be shown when the table is in visually stacked mode.
## Custom empty and emptyfiltered rendering via slots
Aside from using `empty-text`, `empty-filtered-text`, `empty-html`, and `empty-filtered-html`, it is
also possible to provide custom rendering for tables that have no data to display using named slots.
In order for these slots to be shown, the `show-empty` attribute must be set and `items` must be
either falsy or an array of length 0.
```html
<div>
<b-table :fields="fields" :items="items" show-empty>
<template #empty="scope">
<h4>{{ scope.emptyText }}</h4>
</template>
<template #emptyfiltered="scope">
<h4>{{ scope.emptyFilteredText }}</h4>
</template>
</b-table>
</div>
```
The slot can optionally be scoped. The slot's scope (`scope` in the above example) will have the
following properties:
| Property | Type | Description |
| ------------------- | ------ | -------------------------------------------------- |
| `emptyHtml` | String | The `empty-html` prop |
| `emptyText` | String | The `empty-text` prop |
| `emptyFilteredHtml` | String | The `empty-filtered-html` prop |
| `emptyFilteredText` | String | The `empty-filtered-text` prop |
| `fields` | Array | The `fields` prop |
| `items` | Array | The `items` prop. Exposed here to check null vs [] |
## Advanced features
### Sticky headers
Use the `sticky-header` prop to enable a vertically scrolling table with headers that remain fixed
(sticky) as the table body scrolls. Setting the prop to `true` (or no explicit value) will generate
a table that has a maximum height of `300px`. To specify a maximum height other than `300px`, set
the `sticky-header` prop to a valid CSS height (including units), i.e. `sticky-header="200px"`.
Tables with `sticky-header` enabled will also automatically become always responsive horizontally,
regardless of the [`responsive`](#responsive-tables) prop setting, if the table is wider than the
available horizontal space.
```html
<template>
<div>
<b-table sticky-header :items="items" head-variant="light"></b-table>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' },
{ heading1: 'table cell', heading2: 'table cell', heading3: 'table cell' }
]
}
}
}
</script>
<!-- b-table-sticky-header.vue -->
```
**Sticky header notes:**
- The `sticky-header` prop has no effect if the table has the [`stacked`](#stacked-tables) prop set.
- Sticky header tables are wrapped inside a vertically scrollable `<div>` with a maximum height set.
- BootstrapVue's custom CSS is required in order to support `sticky-header`.
- Bootstrap v4 uses the CSS style `border-collapse: collapsed` on table elements. This prevents the
borders on the sticky header from "sticking" to the header, and hence the borders will scroll when
the body scrolls. To get around this issue, set the prop `no-border-collapse` on the table (note
that this may cause double width borders when using features such as `bordered`, etc.).
- The sticky header feature uses CSS style `position: sticky` to position the headings. Internet
Explorer does not support `position: sticky`, hence for IE 11 the table headings will scroll with
the table body.
### Sticky columns
Columns can be made sticky, where they stick to the left of the table when the table has a
horizontal scrollbar. To make a column a sticky column, set the `stickyColumn` prop in the
[field's header definition](#field-definition-reference). Sticky columns will only work when the
table has either the `sticky-header` prop set and/or the [`responsive`](#responsive-tables) prop is
set.
**Example: Sticky columns and headers**
```html
<template>
<div>
<div class="mb-2">
<b-form-checkbox v-model="stickyHeader" inline>Sticky header</b-form-checkbox>
<b-form-checkbox v-model="noCollapse" inline>No border collapse</b-form-checkbox>
</div>
<b-table
:sticky-header="stickyHeader"
:no-border-collapse="noCollapse"
responsive
:items="items"
:fields="fields"
>
<!-- We are using utility class `text-nowrap` to help illustrate horizontal scrolling -->
<template #head(id)="scope">
<div class="text-nowrap">Row ID</div>
</template>
<template #head()="scope">
<div class="text-nowrap">
Heading {{ scope.label }}
</div>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
stickyHeader: true,
noCollapse: false,
fields: [
{ key: 'id', stickyColumn: true, isRowHeader: true, variant: 'primary' },
'a',
'b',
{ key: 'c', stickyColumn: true, variant: 'info' },
'd',
'e',
'f',
'g',
'h',
'i',
'j',
'k',
'l'
],
items: [
{ id: 1, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 2, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 3, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 4, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 5, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 6, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 7, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 8, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 9, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 },
{ id: 10, a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, g: 6, h: 7, i: 8, j: 9, k: 10, l: 11 }
]
}
}
}
</script>
<!-- table-sticky-columns.vue -->
```
**Sticky column notes:**
- Sticky columns has no effect if the table has the [`stacked`](#stacked-tables) prop set.
- Sticky columns tables require either the `sticky-header` and/or `responsive` modes, and are
wrapped inside a horizontally scrollable `<div>`.
- When you have multiple columns that are set as `stickyColumn`, the columns will stack over each
other visually, and the left-most sticky columns may "peek" out from under the next sticky column.
To get around this behaviour, make sure your latter sticky columns are the same width or wider
than previous sticky columns.
- Bootstrap v4 uses the CSS style `border-collapse: collapsed` on table elements. This prevents any
borders on the sticky columns from "sticking" to the column, and hence those borders will scroll
when the body scrolls. To get around this issue, set the prop `no-border-collapse` on the table
(note that this may cause double width borders when using features such as `bordered`, etc.).
- BootstrapVue's custom CSS is required in order to support sticky columns.
- The sticky column feature uses CSS style `position: sticky` to position the column cells. Internet
Explorer does not support `position: sticky`, hence for IE 11 the sticky column will scroll with
the table body.
### Row details support
If you would optionally like to display additional record information (such as columns not specified
in the fields definition array), you can use the scoped slot `row-details`, in combination with the
special item record Boolean property `_showDetails`.
If the record has its `_showDetails` property set to `true`, **and** a `row-details` scoped slot
exists, a new row will be shown just below the item, with the rendered contents of the `row-details`
scoped slot.
In the scoped field slot, you can toggle the visibility of the row's `row-details` scoped slot by
calling the `toggleDetails` function passed to the field's scoped slot variable. You can use the
scoped fields slot variable `detailsShowing` to determine the visibility of the `row-details` slot.
**Note:** If manipulating the `_showDetails` property directly on the item data (i.e. not via the
`toggleDetails` function reference), the `_showDetails` properly **must** exist in the items data
for proper reactive detection of changes to its value. Read more about
[Vue's reactivity limitations](https://vuejs.org/v2/guide/reactivity.html#Change-Detection-Caveats).
**Available `row-details` scoped variable properties:**
| Property | Type | Description |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `item` | Object | The entire row record data object |
| `index` | Number | The current visible row number |
| `fields` | Array | The normalized fields definition array (in the _array of objects_ format) |
| `toggleDetails` | Function | Function to toggle visibility of the row's details slot |
| `rowSelected` | Boolean | Will be `true` if the row has been selected. See section [Row select support](#row-select-support) for additional information |
| `selectRow` | Function | When called, selects the current row. See section [Row select support](#row-select-support) for additional information |
| `unselectRow` | Function | When called, unselects the current row. See section [Row select support](#row-select-support) for additional information |
Note: the row select related scope properties are only available in `<b-table>`.
In the following example, we show two methods of toggling the visibility of the details: one via a
button, and one via a checkbox. We also have the third row details defaulting to have details
initially showing.
```html
<template>
<div>
<b-table :items="items" :fields="fields" striped responsive="sm">
<template #cell(show_details)="row">
<b-button size="sm" @click="row.toggleDetails" class="mr-2">
{{ row.detailsShowing ? 'Hide' : 'Show'}} Details
</b-button>
<!-- As `row.showDetails` is one-way, we call the toggleDetails function on @change -->
<b-form-checkbox v-model="row.detailsShowing" @change="row.toggleDetails">
Details via check
</b-form-checkbox>
</template>
<template #row-details="row">
<b-card>
<b-row class="mb-2">
<b-col sm="3" class="text-sm-right"><b>Age:</b></b-col>
<b-col>{{ row.item.age }}</b-col>
</b-row>
<b-row class="mb-2">
<b-col sm="3" class="text-sm-right"><b>Is Active:</b></b-col>
<b-col>{{ row.item.isActive }}</b-col>
</b-row>
<b-button size="sm" @click="row.toggleDetails">Hide Details</b-button>
</b-card>
</template>
</b-table>
</div>
</template>
<script>
export default {
data() {
return {
fields: ['first_name', 'last_name', 'show_details'],
items: [
{ isActive: true, age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ isActive: false, age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{
isActive: false,
age: 89,
first_name: 'Geneva',
last_name: 'Wilson',
_showDetails: true
},
{ isActive: true, age: 38, first_name: 'Jami', last_name: 'Carney' }
]
}
}
}
</script>
<!-- b-table-details.vue -->
```
### Row select support
You can make rows selectable, by using the `<b-table>` prop `selectable`.
Users can easily change the selecting mode by setting the `select-mode` prop.
- `'multi'`: Each click will select/deselect the row (default mode)
- `'single'`: Only a single row can be selected at one time
- `'range'`: Any row clicked is selected, any other deselected. <kbd>Shift</kbd> + click selects a
range of rows, and <kbd>Ctrl</kbd> (or <kbd>Cmd</kbd>) + click will toggle the selected row.
When a table is `selectable` and the user clicks on a row, `<b-table>` will emit the `row-selected`
event, passing a single argument which is the complete list of selected items. **Treat this argument
as read-only.**
Rows can also be programmatically selected and unselected via the following exposed methods on the
`<b-table>` instance (i.e. via a reference to the table instance via `this.$refs`):
| Method | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `selectRow(index)` | Selects a row with the given `index` number. |
| `unselectRow(index)` | Unselects a row with the given `index` number. |
| `selectAllRows()` | Selects all rows in the table, except in `single` mode in which case only the first row is selected. |
| `clearSelected()` | Unselects all rows. |
| `isRowSelected(index)` | Returns `true` if the row with the given `index` is selected, otherwise it returns `false`. |
**Programmatic row selection notes:**
- `index` is the zero-based index of the table's **visible rows**, after filtering, sorting, and
pagination have been applied.
- In `single` mode, `selectRow(index)` will unselect any previous selected row.
- Attempting to `selectRow(index)` or `unselectRow(index)` on a non-existent row will be ignored.
- The table must be `selectable` for any of these methods to have effect.
- You can disable selection of rows via click events by setting the `no-select-on-click` prop. Rows
will then only be selectable programmatically.
**Row select notes:**
- [Sorting](#sorting), [filtering](#filtering), or [paginating](#pagination) the table will **clear
the active selection**. The `row-selected` event will be emitted with an empty array (`[]`) if
needed.
- When the table is in `selectable` mode, all data item `<tr>` elements will be in the document tab
sequence (`tabindex="0"`) for [accessibility](#accessibility) reasons, and will have the attribute
`aria-selected` set to either `'true'` or `'false'` depending on the selected state of the row.
- When a table is `selectable`, the table will have the attribute `aria-multiselect` set to either
`'false'` for `single` mode, and `'true'` for either `multi` or `range` modes.
When a `<b-table>` is selectable, it will have class `b-table-selectable` and one of the following
three classes (depending on which mode is in use) on the `<table>` element:
- `b-table-select-single`
- `b-table-select-multi`
- `b-table-select-range`
When at least one row is selected, the class `b-table-selecting` will be active on the `<table>`
element. Rows that are selected rows will have a class of `b-table-row-selected` applied to the
`<tr>` element.
Use the prop `selected-variant` to apply a Bootstrap theme color to the selected row(s). Note, due
to the order that the table variants are defined in Bootstrap's CSS, any row-variant _might_ take
precedence over the `selected-variant`. You can set `selected-variant` to an empty string if you
will be using other means to convey that a row is selected (such as a scoped field slot in the below
example).
The `selected-variant` can be any of the
[standard (or custom) Bootstrap base color variants](/docs/reference/color-variants), or the special
[table `active` variant](/docs/reference/color-variants#table-variants) (the default) which takes
precedence over any specific row or cell variants.
For accessibility reasons (specifically for color blind users, or users with color contrast issues),
it is highly recommended to always provide some other visual means of conveying that a row is
selected, such as a virtual column as shown in the example below.
```html
<template>
<div>
<b-form-group
label="Selection mode:"
label-for="table-select-mode-select"
label-cols-md="4"
>
<b-form-select
id="table-select-mode-select"
v-model="selectMode"
:options="modes"
class="mb-3"
></b-form-select>
</b-form-group>
<b-table
:items="items"
:fields="fields"
:select-mode="selectMode"
responsive="sm"
ref="selectableTable"
selectable
@row-selected="onRowSelected"
>
<!-- Example scoped slot for select state illustrative purposes -->
<template #cell(selected)="{ rowSelected }">
<template v-if="rowSelected">
<span aria-hidden="true">✓</span>
<span class="sr-only">Selected</span>
</template>
<template v-else>
<span aria-hidden="true"> </span>
<span class="sr-only">Not selected</span>
</template>
</template>
</b-table>
<p>
<b-button size="sm" @click="selectAllRows">Select all</b-button>
<b-button size="sm" @click="clearSelected">Clear selected</b-button>
<b-button size="sm" @click="selectThirdRow">Select 3rd row</b-button>
<b-button size="sm" @click="unselectThirdRow">Unselect 3rd row</b-button>
</p>
<p>
Selected Rows:<br>
{{ selected }}
</p>
</div>
</template>
<script>
export default {
data() {
return {
modes: ['multi', 'single', 'range'],
fields: ['selected', 'isActive', 'age', 'first_name', 'last_name'],
items: [
{ isActive: true, age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ isActive: false, age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ isActive: false, age: 89, first_name: 'Geneva', last_name: 'Wilson' },
{ isActive: true, age: 38, first_name: 'Jami', last_name: 'Carney' }
],
selectMode: 'multi',
selected: []
}
},
methods: {
onRowSelected(items) {
this.selected = items
},
selectAllRows() {
this.$refs.selectableTable.selectAllRows()
},
clearSelected() {
this.$refs.selectableTable.clearSelected()
},
selectThirdRow() {
// Rows are indexed from 0, so the third row is index 2
this.$refs.selectableTable.selectRow(2)
},
unselectThirdRow() {
// Rows are indexed from 0, so the third row is index 2
this.$refs.selectableTable.unselectRow(2)
}
}
}
</script>
<!-- b-table-selectable.vue -->
```
### Table body transition support
Vue transitions and animations are optionally supported on the `<tbody>` element via the use of
Vue's `<transition-group>` component internally. Three props are available for transitions support
(all three default to undefined):
| Prop | Type | Description |
| --------------------------- | ------ | ----------------------------------------------------------------- |
| `tbody-transition-props` | Object | Object of transition-group properties |
| `tbody-transition-handlers` | Object | Object of transition-group event handlers |
| `primary-key` | String | String specifying the field to use as a unique row key (required) |
To enable transitions you need to specify `tbody-transition-props` and/or
`tbody-transition-handlers`, and must specify which field key to use as a unique key via the
`primary-key` prop. Your data **must have** a column (specified by setting the `primary-key` prop to
the _name_ of the field) that has a **unique value per row** in order for transitions to work
properly. The `primary-key` field's _value_ can either be a unique string or number. The field
specified does not need to appear in the rendered table output, but it **must** exist in each row of
your items data.
You must also provide CSS to handle your transitions (if using CSS transitions) in your project.
For more information of Vue's list rendering transitions, see the
[Vue JS official docs](https://vuejs.org/v2/guide/transitions.html#List-Move-Transitions).
In the example below, we have used the following custom CSS:
```css
table#table-transition-example .flip-list-move {
transition: transform 1s;
}
```
```html
<template>
<div>
<b-table
id="table-transition-example"
:items="items"
:fields="fields"
striped
small
primary-key="a"
:tbody-transition-props="transProps"
></b-table>
</div>
</template>
<script>
export default {
data() {
return {
transProps: {
// Transition name
name: 'flip-list'
},
items: [
{ a: 2, b: 'Two', c: 'Moose' },
{ a: 1, b: 'Three', c: 'Dog' },
{ a: 3, b: 'Four', c: 'Cat' },
{ a: 4, b: 'One', c: 'Mouse' }
],
fields: [
{ key: 'a', sortable: true },
{ key: 'b', sortable: true },
{ key: 'c', sortable: true }
]
}
}
}
</script>
<!-- b-table-transitions.vue -->
```
### `v-model` binding
If you bind a variable to the `v-model` prop, the contents of this variable will be the currently
displayed item records (zero based index, up to `page-size` - 1). This variable (the `value` prop)
should usually be treated as _readonly_.
The records within the `v-model` are a filtered/paginated _shallow copy_ of `items`, and hence any
changes to a record's properties in the `v-model` will be reflected in the original `items` array
(except when `items` is set to a provider function). Deleting a record from the `v-model` array will
**not** remove the record from the original items array nor will it remove it from the displayed
rows.
**Note:** Do not bind any value directly to the `value` prop. Use the `v-model` binding.
## Sorting
As mentioned in the [Fields](#fields-column-definitions) section above, you can make columns
sortable in `<b-table>`. Clicking on a sortable column header will sort the column in ascending
direction (smallest first), while clicking on it again will switch the direction of sorting to
descending (largest first). Clicking on a non-sortable column will clear the sorting (the prop
`no-sort-reset` can be used to disable this feature).
You can control which column is pre-sorted and the order of sorting (ascending or descending). To
pre-specify the column to be sorted, set the `sort-by` prop to the field's key. Set the sort
direction by setting `sort-desc` to either `true` (for descending) or `false` (for ascending, the
default).
- **Ascending**: Items are sorted lowest to highest (i.e. `A` to `Z`) and will be displayed with the
lowest value in the first row with progressively higher values in the following rows.
- **Descending**: Items are sorted highest to lowest (i.e. `Z` to `A`) and will be displayed with
the highest value in the first row with progressively lower values in the following rows.
The props `sort-by` and `sort-desc` can be turned into _two-way_ (syncable) props by adding the
`.sync` modifier. Your bound variables will then be updated accordingly based on the current sort
criteria. See the [Vue docs](https://vuejs.org/v2/guide/components.html#sync-Modifier) for details
on the `.sync` prop modifier.
Setting `sort-by` to a column that is not defined in the fields as `sortable` will result in the
table not being sorted.
When the prop `foot-clone` is set, the footer headings will also allow sorting by clicking, even if
you have custom formatted footer field headers. To disable the sort icons and sorting via heading
clicks in the footer, set the `no-footer-sorting` prop to true.
```html
<template>
<div>
<b-table
:items="items"
:fields="fields"
:sort-by.sync="sortBy"
:sort-desc.sync="sortDesc"
responsive="sm"
></b-table>
<div>
Sorting By: <b>{{ sortBy }}</b>, Sort Direction:
<b>{{ sortDesc ? 'Descending' : 'Ascending' }}</b>
</div>
</div>
</template>
<script>
export default {
data() {
return {
sortBy: 'age',
sortDesc: false,
fields: [
{ key: 'last_name', sortable: true },
{ key: 'first_name', sortable: true },
{ key: 'age', sortable: true },
{ key: 'isActive', sortable: false }
],
items: [
{ isActive: true, age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ isActive: false, age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ isActive: false, age: 89, first_name: 'Geneva', last_name: 'Wilson' },
{ isActive: true, age: 38, first_name: 'Jami', last_name: 'Carney' }
]
}
}
}
</script>
<!-- b-table-sorting.vue -->
```
### Sort icon alignment
By default the sorting icons appear right aligned in the header cell. You can change the icons to be
left aligned by setting the prop `sort-icon-left` on `<b-table>`.
```html
<template>
<div>
<b-table
:items="items"
:fields="fields"
:sort-by.sync="sortBy"
:sort-desc.sync="sortDesc"
sort-icon-left
responsive="sm"
></b-table>
<div>
Sorting By: <b>{{ sortBy }}</b>, Sort Direction:
<b>{{ sortDesc ? 'Descending' : 'Ascending' }}</b>
</div>
</div>
</template>
<script>
export default {
data() {
return {
sortBy: 'age',
sortDesc: false,
fields: [
{ key: 'last_name', sortable: true },
{ key: 'first_name', sortable: true },
{ key: 'age', sortable: true },
{ key: 'isActive', sortable: false }
],
items: [
{ isActive: true, age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
{ isActive: false, age: 21, first_name: 'Larsen', last_name: 'Shaw' },
{ isActive: false, age: 89, first_name: 'Geneva', last_name: 'Wilson' },
{ isActive: true, age: 38, first_name: 'Jami', last_name: 'Carney' }
]
}
}
}
</script>
<!-- b-table-sorting-left.vue -->
```
### Customizing the sort icons
The sorting icons are generated via the use of SVG background images. The icons can be altered by
updating BootstrapVue's SASS/SCSS variables and recompiling the SCSS source code. Refer to the
[theming](/docs/reference/theming) section for details on customizing Bootstrap and BootstrapVue's
generated CSS.
### Sort-compare routine
The internal built-in default `sort-compare` function sorts the specified field `key` based on the
data in the underlying record object (or by formatted value if a field has a formatter function, and
the field has its `sortByFormatted` property is set to `true`). The field value is first stringified
if it is an object and then sorted.
**Notes:**
- The built-in `sort-compare` routine **cannot** sort based on the custom rendering of the field
data: scoped slots are used only for _presentation only_, and do not affect the underlying data.
- Fields that have a [`formatter` function](#formatter-callback) (virtual field or regular field)
can be sorted by the value returned via the formatter function if the
[field](#field-definition-reference) property `sortByFormatted` is set to `true`. Optionally you
can pass a formatter function reference to `sortByFormatted` to format the value before sorting.
The default is `false` which will sort by the original field value. This is only applicable for
the built-in sort-compare routine.
- By default, the internal sorting routine will sort `null`, `undefined`, or empty string values
first (less than any other values). To sort so that `null`, `undefined` or empty string values
appear last (greater than any other value), set the `sort-null-last` prop to `true`.
For customizing the sort-compare handling, refer to the
[Custom sort-compare routine](#custom-sort-compare-routine) section below.
### Internal sorting and locale handling
The internal sort-compare routine uses
[`String.prototype.localeCompare()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare)
for comparing the stringified column value (if values being compared are not both `Number` or both
`Date` types). The browser native `localeCompare()` method accepts a `locale` string (or array of
locale strings) and an `options` object for controlling how strings are sorted. The default options
are `{ numeric: true }`, and the locale is `undefined` (which uses the browser default locale).
You can change the locale (or locales) via the `sort-compare-locale` prop to set the locale(s) for
sorting, as well as pass sort options via the `sort-compare-options` prop.
The `sort-compare-locale` prop defaults to `undefined`, which uses the browser (or Node.js runtime)
default locale. The prop `sort-compare-locale` can either accept a
[BCP 47 language tag](https://tools.ietf.org/html/rfc5646) string or an _array_ of such tags. For
more details on locales, please see
[Locale identification and negotiation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation)
on MDN.
The `sort-compare-options` prop accepts an object containing any of the following properties:
- `localeMatcher`: The locale matching algorithm to use. Possible values are `'lookup'` and
`'best fit'`. The default is `'best fit'`. For information about this option, see the
[MDN Intl page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation)
for details.
- `sensitivity`: Which differences in the strings should lead to _non-zero_ compare result values.
Possible values are:
- `'base'`: Only strings that differ in base letters compare as unequal. Examples: `a ≠ b`,
`a = á`, `a = A`.
- `'accent'`: Only strings that differ in base letters or accents and other diacritic marks
compare as unequal. Examples: `a ≠ b`, `a ≠ á`, `a = A`.
- `'case'`: Only strings that differ in base letters or case compare as unequal. Examples:
`a ≠ b`, `a = á`, `a ≠ A`.
- `'variant'`: **(default)** Strings that differ in base letters, accents and other diacritic
marks, or case compare as unequal. Other differences _may also_ be taken into consideration.
Examples: `a ≠ b`, `a ≠ á`, `a ≠ A`.
- `ignorePunctuation`: Whether punctuation should be ignored. Possible values are `true` and
`false`. The default is `false`.
- `numeric`: Whether numeric collation should be used, such that `'1' < '2' < '10'`. Possible values
are `true` and `false`. The default is `false`. Note that implementations (browsers, runtimes) are
not required to support this property, and therefore it might be ignored.
- `caseFirst`: Whether upper case or lower case should sort first. Possible values are `'upper'`,
`'lower'`, or `'false'` (use the locale's default). The default is `'false'`. Implementations are
not required to support this property.
- `'usage'`: **Always** set to `'sort'` by `<b-table>`
**Example 1:** If you want to sort German words, set `sort-compare-locale="de"` (in German, `ä`
sorts _before_ `z`) or Swedish set `sort-compare-locale="sv"` (in Swedish, `ä` sorts _after_ `z`)
**Example 2:** To compare numbers that are strings numerically, and to ignore case and accents:
```html
<b-table :sort-compare-options="{ numeric: true, sensitivity: 'base' }" ...>
```
**Notes:**
- Refer to
[MDN `String.prototype.localeCompare()` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare)
for details on the options object property values.
- Refer to
[MDN locales documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)
for details on locale values.
- Not all browsers (or Node.js) support the `locale` and `options` with
`String.prototype.localeCompare()`. Refer to [Can I use](https://caniuse.com/localecompare) for
browser support. For Node.js, you may need to add in
[Intl support](https://nodejs.org/api/intl.html) for handling locales, other than the default, to
prevent [SSR hydration mismatch errors](https://ssr.vuejs.org/guide/hydration.html).
### Custom sort-compare routine
You can provide your own custom sort compare routine by passing a function reference to the prop
`sort-compare`. The `sort-compare` routine is passed seven (7) arguments, of which the last 4 are
optional:
- the first two arguments (`a` and `b`) are the _record objects_ for the rows being compared
- the third argument is the field `key` being sorted on (`sortBy`)
- the fourth argument (`sortDesc`) is the order `<b-table>` will be displaying the records (`true`
for descending, `false` for ascending)
- the fifth argument is a reference to the field's [formatter function](#formatter-callback) or the
field's `filterByFormatted` value if it is a function reference. If not formatter is found this
value will be `undefined`. You will need to call this method to get the formatted field value:
`valA = formatter(a[key], key, a)` and `valB = formatter(b[key], key, b)`, if you need to sort by
the formatted value. This will be `undefined` if the field's `sortByFormatted` property is not
`true` or is not a formatter function _reference_, or the fields formatter function cannot be
found.
- the sixth argument is the value of the `sort-compare-options` prop (default is
`{ numeric: true }`)
- the seventh argument is the value of the `sort-compare-locale` prop (default is `undefined`)
The sixth and seventh arguments can be used if you are using the
[`String.prototype.localeCompare()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare)
method to compare strings.
In most typical situations, you only need to use the first three arguments. The fourth argument -
sorting direction - should not normally be used, as `b-table` will handle the direction, and this
value is typically only needed when special handling of how `null` and/or `undefined` values are
sorted (i.e. sorting `null`/`undefined` first or last).
The routine should return either `-1` (or a negative value) for `a[key] < b[key]` , `0` for
`a[key] === b[key]`, or `1` (or a positive value) for `a[key] > b[key]`.
Your custom sort-compare routine can also return `null` or `false`, to fall back to the _built-in
sort-compare routine_ for the particular `key`. You can use this feature (i.e. by returning `null`)
to have your custom sort-compare routine handle _only_ certain fields (keys) such as the special
case of virtual (scoped slot) columns, and have the internal (built in) sort-compare handle all
_other_ fields.
The default sort-compare routine works similar to the following. Note the fourth argument (sorting
direction) is **not** used in the sort comparison:
<!-- eslint-disable no-unused-vars, no-undef -->
```js
function sortCompare(aRow, bRow, key, sortDesc, formatter, compareOptions, compareLocale) {
const a = aRow[key] // or use Lodash `_.get()`
const b = bRow[key]
if (
(typeof a === 'number' && typeof b === 'number') ||
(a instanceof Date && b instanceof Date)
) {
// If both compared fields are native numbers or both are native dates
return a < b ? -1 : a > b ? 1 : 0
} else {
// Otherwise stringify the field data and use String.prototype.localeCompare
return toString(a).localeCompare(toString(b), compareLocale, compareOptions)
}
}
// Helper function to stringify the values of an Object
function toString(value) {
if (value === null || typeof value === 'undefined') {
return ''
} else if (value instanceof Object) {
return Object.keys(value)
.sort()
.map(key => toString(value[key]))
.join(' ')
} else {
return String(value)
}
}
```
### Disable local sorting
If you want to handle sorting entirely in your app, you can disable the local sorting in `<b-table>`
by setting the prop `no-local-sorting` to `true`, while still maintaining the sortable header
functionality (via `sort-changed` or `context-changed` events as well as syncable props).
You can use the syncable props `sort-by.sync` and `sort-desc.sync` to detect changes in sorting
column and direction.
Also, When a sortable column header (or footer) is clicked, the event `sort-changed` will be emitted
with a single argument containing the context object of `<b-table>`. See the
[Detection of sorting change](#detection-of-sorting-change) section below for details about the
sort-changed event and the context object.
When `no-local-sorting` is `true`, the `sort-compare` prop has no effect.
### Change initial sort direction
Control the order in which ascending and descending sorting is applied when a sortable column header
is clicked, by using the `sort-direction` prop. The default value `'asc'` applies ascending sort
first (when a column is not currently sorted). To reverse the behavior and sort in descending
direction first, set it to `'desc'`.
If you don't want the current sorting direction to change when clicking another sortable column
header, set `sort-direction` to `'last'`. This will maintain the sorting direction of the previously
sorted column.
For individual column initial sort direction (which applies when the column transitions from
unsorted to sorted), specify the property `sortDirection` in `fields`. See the
[Complete Example](#complete-example) below for an example of using this feature.
## Filtering
Filtering, when used, is applied by default to the **original items** array data. `b-table` provides
several options for how data is filtered.
It is currently not possible to filter based on result of formatting via
[scoped field slots](#scoped-field-slots).
### Built in filtering
The item's row data values are stringified (see the sorting section above for how stringification is
done) and the filter searches that stringified data (excluding any of the special properties that
begin with an underscore `'_'`). The stringification also, by default, includes any data not shown
in the presented columns.
With the default built-in filter function, the `filter` prop value can either be a string or a
`RegExp` object (regular expressions should _not_ have the `/g` global flag set).
If the stringified row contains the provided string value or matches the RegExp expression then it
is included in the displayed results.
Set the `filter` prop to `null` or an empty string to clear the current filter.
### Built in filtering options
There are several options for controlling what data the filter is applied against.
- The `filter-ignored-fields` prop accepts an array of _top-level_ (immediate properties of the row
data) field keys that should be ignored when filtering.
- The `filter-included-fields` prop accepts an array of _top-level_ (immediate properties of the row
data) field keys that should used when filtering. All other field keys not included in this array
will be ignored. This feature can be handy when you want to filter on specific columns. If the
specified array is empty, then _all_ fields are included, except those specified via the prop
`filter-ignored-fields`. If a field key is specified in both `filter-ignored-fields` and
`filter-included-fields`, then `filter-included-fields` takes precedence.
- Normally, `<b-table>` filters based on the stringified record data. If the field has a `formatter`
function specified, you can optionally filter based on the result of the formatter by setting the
[field definition property](#field-definition-reference) `filterByFormatted` to `true`. If the
field does not have a formatter function, this option is ignored. You can optionally pass a
formatter function _reference_, to be used for filtering only, to the field definition property
`filterByFormatted`.
The props `filter-ignored-fields` and `filter-included-fields`, and the field definition property
`filterByFormatted` have no effect when using a [custom filter function](#custom-filter-function),
or [items provider](#using-items-provider-functions) based filtering.
### Custom filter function
You can also use a custom filter function, by setting the prop `filter-function` to a reference of
custom filter test function. The filter function will be passed two arguments:
- the original item row record data object. **Treat this argument as read-only.**
- the content of the `filter` prop (could be a string, RegExp, array, or object)
The function should return `true` if the record matches your criteria or `false` if the record is to
be filtered out.
For proper reactive updates to the displayed data, when not filtering you should set the `filter`
prop to `null` or an empty string (and not an empty object or array). The filter function will not
be called when the `filter` prop is a falsey value.
The display of the `empty-filter-text` relies on the truthiness of the `filter` prop.
### Filter events
When local filtering is applied, and the resultant number of items change, `<b-table>` will emit the
`filtered` event with a two arguments:
- an array reference which is the complete list of items passing the filter routine. **Treat this
argument as read-only.**
- the number of records that passed the filter test (the length of the first argument)
Setting the prop `filter` to null or an empty string will clear local items filtering.
### Debouncing filter criteria changes
<span class="badge badge-warning small">deprecated in v2.1.0</span> Use the `debounce` feature of
[`<b-form-input>`](/docs/components/form-input#debounce-support) instead.
If you have a text input tied to the `filter` prop of `<b-table>`, the filtering process will occur
for each character typed by the user. With large items datasets, this process can take a while and
may cause the text input to appear sluggish.
To help alleviate this type of situation, `<b-table>` accepts a debounce timeout value (in
milliseconds) via the `filter-debounce` prop. The default is `0` (milliseconds). When a value
greater than `0` is provided, the filter will wait for that time before updating the table results.
If the value of the `filter` prop changes before this timeout expires, the filtering will be once
again delayed until the debounce timeout expires.
When used, the suggested value of `filter-debounce` should be in the range of `100` to `200`
milliseconds, but other values may be more suitable for your use case.
The use of this prop can be beneficial when using provider filtering with
[items provider functions](#using-items-provider-functions), to help reduce the number of calls to
your back end API.
### Filtering notes
See the [Complete Example](#complete-example) below for an example of using the `filter` feature.
## Pagination
`<b-table>` supports built in pagination of item data. You can control how many rows are displayed
at a time by setting the `per-page` prop to the maximum number of rows you would like displayed, and
use the `current-page` prop to specify which page to display (starting from page `1`). If you set
`current-page` to a value larger than the computed number of pages, then no rows will be shown.
You can use the [`<b-pagination>`](/docs/components/pagination) component in conjunction with
`<b-table>` for providing control over pagination.
Setting `per-page` to `0` (default) will disable the local items pagination feature.
## Using items provider functions
As mentioned under the [Items](#items-record-data) prop section, it is possible to use a function to
provide the row data (items), by specifying a function reference via the `items` prop.
The provider function is called with the following signature:
<!-- eslint-disable no-undef -->
```js
provider(ctx, [callback])
```
The `ctx` is the context object associated with the table state, and contains the following
properties:
| Property | Type | Description |
| ------------- | -------------------------- | --------------------------------------------------------------------------------- |
| `currentPage` | Number | The current page number (starting from 1, the value of the `current-page` prop) |
| `perPage` | Number | The maximum number of rows per page to display (the value of the `per-page` prop) |
| `filter` | String or RegExp or Object | The value of the `filter` prop |
| `sortBy` | String | The current column key being sorted, or an empty string if not sorting |
| `sortDesc` | Boolean | The current sort direction (`true` for descending, `false` for ascending) |
| `apiUrl` | String | The value provided to the `api-url` prop. `null` if none provided. |
The second argument `callback` is an optional parameter for when using the callback asynchronous
method.
**Example: returning an array of data (synchronous):**
<!-- eslint-disable no-unused-vars, prefer-const -->
```js
function myProvider() {
let items = []
// Perform any items processing needed
// Must return an array
return items || []
}
```
**Example: Using callback to return data (asynchronous):**
<!-- eslint-disable no-unused-vars, node/no-callback-literal -->
```js
function myProvider(ctx, callback) {
const params = '?page=' + ctx.currentPage + '&size=' + ctx.perPage
this.fetchData('/some/url' + params)
.then(data => {
// Pluck the array of items off our axios response
const items = data.items
// Provide the array of items to the callback
callback(items)
})
.catch(() => {
callback([])
})
// Must return null or undefined to signal b-table that callback is being used
return null
}
```
**Example: Using a Promise to return data (asynchronous):**
<!-- eslint-disable no-unused-vars, no-undef -->
```js
function myProvider(ctx) {
const promise = axios.get('/some/url?page=' + ctx.currentPage + '&size=' + ctx.perPage)
// Must return a promise that resolves to an array of items
return promise.then(data => {
// Pluck the array of items off our axios response
const items = data.items
// Must return an array of items or an empty array if an error occurred
return items || []
})
}
```
**Example: Using an async function (semi-synchronous):**
Using an async method to return an items array is possible:
<!-- eslint-disable no-unused-vars, no-undef -->
```js
async function myProvider(ctx) {
try {
const response = await axios.get(`/some/url?page=${ctx.currentPage}&size=${ctx.perPage}`)
return response.items
} catch (error) {
return []
}
}
```
Note that not all browsers support `async/await` natively. For browsers that do not support `async`
methods, you will need to transpile your code.
### Automated table busy state
`<b-table>` automatically tracks/controls its `busy` state when items provider functions are used,
however it also provides a `busy` prop that can be used either to override the inner `busy` state,
or to monitor `<b-pagination>`'s current busy state in your application using the 2-way `.sync`
modifier.
**Note:** in order to allow `<b-table>` fully track its `busy` state, the custom items provider
function should handle errors from data sources and return an empty array to `<b-table>`.
**Example: usage of busy state**
```html
<template>
<div>
<b-table
id="my-table"
:busy.sync="isBusy"
:items="myProvider"
:fields="fields"
...
></b-table>
</div>
</template>
<script>
export default {
data () {
return {
isBusy: false
}
}
methods: {
myProvider () {
// Here we don't set isBusy prop, so busy state will be
// handled by table itself
// this.isBusy = true
let promise = axios.get('/some/url')
return promise.then((data) => {
const items = data.items
// Here we could override the busy state, setting isBusy to false
// this.isBusy = false
return(items)
}).catch(error => {
// Here we could override the busy state, setting isBusy to false
// this.isBusy = false
// Returning an empty array, allows table to correctly handle
// internal busy state in case of error
return []
})
}
}
}
</script>
```
If using an `async/await` provider:
<!-- eslint-disable no-unused-vars, no-undef -->
```js
async function myProvider(ctx) {
this.isBusy = true
try {
const response = await axios.get(`/some/url?page=${ctx.currentPage}&size=${ctx.perPage}`)
this.isBusy = false
return response.items
} catch (error) {
this.isBusy = false
return []
}
}
```
**Notes:**
- If you manually place the table in the `busy` state, the items provider will **not** be
called/refreshed until the `busy` state has been set to `false`.
- All click related and hover events, and sort-changed events will **not** be emitted when in the
`busy` state (either set automatically during provider update, or when manually set).
### Provider paging, filtering, and sorting
By default, the items provider function is responsible for **all paging, filtering, and sorting** of
the data, before passing it to `b-table` for display.
You can disable provider paging, filtering, and sorting (individually) by setting the following
`b-table` prop(s) to `true`:
| Prop | Type | Default | Description |
| ----------------------- | ------- | ------- | -------------------------------------------------------------- |
| `no-provider-paging` | Boolean | `false` | When `true` enables the use of `b-table` local data pagination |
| `no-provider-sorting` | Boolean | `false` | When `true` enables the use of `b-table` local sorting |
| `no-provider-filtering` | Boolean | `false` | When `true` enables the use of `b-table` local filtering |
When `no-provider-paging` is `false` (default), you should only return at maximum, `perPage` number
of records.
**Notes:**
- `<b-table>` needs reference to your pagination and filtering values in order to trigger the
calling of the provider function. So be sure to bind to the `per-page`, `current-page` and
`filter` props on `b-table` to trigger the provider update function call (unless you have the
respective `no-provider-*` prop set to `true`).
- The `no-local-sorting` prop has no effect when `items` is a provider function.
- When using provider filtering, you may find that setting the
[`debounce` prop on `<b-form-input>`](/docs/components/form-input#debounce-support) to a value
greater than `100` ms will help minimize the number of calls to your back end API as the user
types in the criteria.
### Force refreshing of table data
You may also trigger the refresh of the provider function by emitting the event `refresh::table` on
`$root` with the single argument being the `id` of your `b-table`. You must have a unique ID on your
table for this to work.
```js
this.$root.$emit('bv::refresh::table', 'my-table')
```
Or by calling the `refresh()` method on the table reference
```html
<div>
<b-table ref="table" ... ></b-table>
</div>
```
```js
this.$refs.table.refresh()
```
**Note:** If the table is in the `busy` state (i.e. a provider update is currently running), the
refresh will wait until the current update is completed. If there is currently a refresh pending and
a new refresh is requested, then only one refresh will occur.
### Detection of sorting change
By listening on `<b-table>` `sort-changed` event, you can detect when the sorting key and direction
have changed.
```html
<div>
<b-table @sort-changed="sortingChanged" ... ></b-table>
</div>
```
The `sort-changed` event provides a single argument of the table's current state context object.
This context object has the same format as used by items provider functions.
<!-- eslint-disable no-unused-vars -->
```js
export default {
methods: {
sortingChanged(ctx) {
// ctx.sortBy ==> Field key for sorting by (or null for no sorting)
// ctx.sortDesc ==> true if sorting descending, false otherwise
}
}
}
```
You can also obtain the current sortBy and sortDesc values by using the `:sort-by.sync` and
`:sort-desc.sync` two-way props respectively (see section [Sorting](#sorting) above for details).
```html
<div>
<b-table :sort-by.sync="mySortBy" :sort-desc.sync="mySortDesc" ... ></b-table>
</div>
```
### Server side rendering
Special care must be taken when using server side rendering (SSR) and an `items` provider function.
Make sure you handle any special situations that may be needed server side when fetching your data!
When `<b-table>` is mounted in the document, it will automatically trigger a provider update call.
## Light-weight tables
`<b-table-lite>` provides a great alternative to `<b-table>` if you just need simple display of
tabular data. The `<b-table-lite>` component provides all of the styling and formatting features of
`<b-table>` (including row details and stacked support), while **excluding** the following features:
- Filtering
- Sorting
- Pagination
- Items provider support
- Selectable rows
- Busy table state and styling
- Fixed top and bottom rows
- Empty row support
### Table lite as a plugin
The `TablePlugin` includes `<b-table-lite>`. For convenience, BootstrapVue also provides a
`TableLitePlugin` which installs only `<b-table-lite>`. `TableLitePlugin` is available as a top
level named export.
## Simple tables
The `<b-table-simple>` component gives the user complete control over the rendering of the table
content, while providing basic Bootstrap v4 table styling. `<b-table-simple>` is a wrapper component
around the `<table>` element. Inside the component, via the `default` slot, you can use any or all
of the BootstrapVue [table helper components](#table-helper-components): `<b-thead>`, `<b-tfoot>`,
`<b-tbody>`, `<b-tr>`, `<b-th>`, `<b-td>`, and the HTML5 elements `<caption>`, `<colgroup>` and
`<col>`. Contrary to the component's name, one can create simple or complex table layouts with
`<b-table-simple>`.
`<b-table-simple>` provides basic styling options via props: `striped`, `bordered`, `borderless`,
`outlined`, `small`, `hover`, `dark`, `fixed`, `responsive` and `sticky-header`. Note that `stacked`
mode is available but requires some additional markup to generate the cell headings, as described in
the [Simple tables and stacked mode](#simple-tables-and-stacked-mode) section below. Sticky columns
are also supported, but also require a bit of additional markup to specify which columns are to be
sticky. See below for more information on using [sticky columns](#simple-tables-and-sticky-columns).
Since `b-table-simple` is just a wrapper component, of which you will need to render content inside,
it does not provide any of the advanced features of `<b-table>` (i.e. row events, head events,
sorting, pagination, filtering, foot-clone, items, fields, etc.).
```html
<div>
<b-table-simple hover small caption-top responsive>
<caption>Items sold in August, grouped by Country and City:</caption>
<colgroup><col><col></colgroup>
<colgroup><col><col><col></colgroup>
<colgroup><col><col></colgroup>
<b-thead head-variant="dark">
<b-tr>
<b-th colspan="2">Region</b-th>
<b-th colspan="3">Clothes</b-th>
<b-th colspan="2">Accessories</b-th>
</b-tr>
<b-tr>
<b-th>Country</b-th>
<b-th>City</b-th>
<b-th>Trousers</b-th>
<b-th>Skirts</b-th>
<b-th>Dresses</b-th>
<b-th>Bracelets</b-th>
<b-th>Rings</b-th>
</b-tr>
</b-thead>
<b-tbody>
<b-tr>
<b-th rowspan="3">Belgium</b-th>
<b-th class="text-right">Antwerp</b-th>
<b-td>56</b-td>
<b-td>22</b-td>
<b-td>43</b-td>
<b-td variant="success">72</b-td>
<b-td>23</b-td>
</b-tr>
<b-tr>
<b-th class="text-right">Gent</b-th>
<b-td>46</b-td>
<b-td variant="warning">18</b-td>
<b-td>50</b-td>
<b-td>61</b-td>
<b-td variant="danger">15</b-td>
</b-tr>
<b-tr>
<b-th class="text-right">Brussels</b-th>
<b-td>51</b-td>
<b-td>27</b-td>
<b-td>38</b-td>
<b-td>69</b-td>
<b-td>28</b-td>
</b-tr>
<b-tr>
<b-th rowspan="2">The Netherlands</b-th>
<b-th class="text-right">Amsterdam</b-th>
<b-td variant="success">89</b-td>
<b-td>34</b-td>
<b-td>69</b-td>
<b-td>85</b-td>
<b-td>38</b-td>
</b-tr>
<b-tr>
<b-th class="text-right">Utrecht</b-th>
<b-td>80</b-td>
<b-td variant="danger">12</b-td>
<b-td>43</b-td>
<b-td>36</b-td>
<b-td variant="warning">19</b-td>
</b-tr>
</b-tbody>
<b-tfoot>
<b-tr>
<b-td colspan="7" variant="secondary" class="text-right">
Total Rows: <b>5</b>
</b-td>
</b-tr>
</b-tfoot>
</b-table-simple>
</div>
<!-- b-table-simple.vue -->
```
When in `responsive` or `sticky-header` mode, the `<table>` element is wrapped inside a `<div>`
element. If you need to apply additional classes to the `<table>` element, use the `table-classes`
prop.
Any additional attributes given to `<b-table-simple>` will always be applied to the `<table>`
element.
### Simple tables and stacked mode
A bit of additional markup is required on your `<b-table-simple>` body cells when the table is in
stacked mode. Specifically, BootstrapVue uses a special data attribute to create the cell's heading,
of which you can supply to `<b-td>` or `<b-th>` via the `stacked-heading` prop. Only plain strings
are supported (not HTML markup), as we use the pseudo element `::before` and css `content` property.
Here is the same table as above, set to be always stacked, which has the extra markup to handle
stacked mode (specifically for generating the cell headings):
```html
<div>
<b-table-simple hover small caption-top stacked>
<caption>Items sold in August, grouped by Country and City:</caption>
<colgroup><col><col></colgroup>
<colgroup><col><col><col></colgroup>
<colgroup><col><col></colgroup>
<b-thead head-variant="dark">
<b-tr>
<b-th colspan="2">Region</b-th>
<b-th colspan="3">Clothes</b-th>
<b-th colspan="2">Accessories</b-th>
</b-tr>
<b-tr>
<b-th>Country</b-th>
<b-th>City</b-th>
<b-th>Trousers</b-th>
<b-th>Skirts</b-th>
<b-th>Dresses</b-th>
<b-th>Bracelets</b-th>
<b-th>Rings</b-th>
</b-tr>
</b-thead>
<b-tbody>
<b-tr>
<b-th rowspan="3" class="text-center">Belgium (3 Cities)</b-th>
<b-th stacked-heading="City" class="text-left">Antwerp</b-th>
<b-td stacked-heading="Clothes: Trousers">56</b-td>
<b-td stacked-heading="Clothes: Skirts">22</b-td>
<b-td stacked-heading="Clothes: Dresses">43</b-td>
<b-td stacked-heading="Accessories: Bracelets" variant="success">72</b-td>
<b-td stacked-heading="Accessories: Rings">23</b-td>
</b-tr>
<b-tr>
<b-th stacked-heading="City">Gent</b-th>
<b-td stacked-heading="Clothes: Trousers">46</b-td>
<b-td stacked-heading="Clothes: Skirts" variant="warning">18</b-td>
<b-td stacked-heading="Clothes: Dresses">50</b-td>
<b-td stacked-heading="Accessories: Bracelets">61</b-td>
<b-td stacked-heading="Accessories: Rings" variant="danger">15</b-td>
</b-tr>
<b-tr>
<b-th stacked-heading="City">Brussels</b-th>
<b-td stacked-heading="Clothes: Trousers">51</b-td>
<b-td stacked-heading="Clothes: Skirts">27</b-td>
<b-td stacked-heading="Clothes: Dresses">38</b-td>
<b-td stacked-heading="Accessories: Bracelets">69</b-td>
<b-td stacked-heading="Accessories: Rings">28</b-td>
</b-tr>
<b-tr>
<b-th rowspan="2" class="text-center">The Netherlands (2 Cities)</b-th>
<b-th stacked-heading="City">Amsterdam</b-th>
<b-td stacked-heading="Clothes: Trousers" variant="success">89</b-td>
<b-td stacked-heading="Clothes: Skirts">34</b-td>
<b-td stacked-heading="Clothes: Dresses">69</b-td>
<b-td stacked-heading="Accessories: Bracelets">85</b-td>
<b-td stacked-heading="Accessories: Rings">38</b-td>
</b-tr>
<b-tr>
<b-th stacked-heading="City">Utrecht</b-th>
<b-td stacked-heading="Clothes: Trousers">80</b-td>
<b-td stacked-heading="Clothes: Skirts" variant="danger">12</b-td>
<b-td stacked-heading="Clothes: Dresses">43</b-td>
<b-td stacked-heading="Accessories: Bracelets">36</b-td>
<b-td stacked-heading="Accessories: Rings" variant="warning">19</b-td>
</b-tr>
</b-tbody>
<b-tfoot>
<b-tr>
<b-td colspan="7" variant="secondary" class="text-right">
Total Rows: <b>5</b>
</b-td>
</b-tr>
</b-tfoot>
</b-table-simple>
</div>
<!-- b-table-simple-stacked.vue -->
```
Like `<b-table>` and `<b-table-lite>`, table headers (`<thead>`) and footers (`<tfoot>`) are
visually hidden when the table is visually stacked. If you need a header or footer, you can do so by
creating an extra `<b-tr>` inside of the `<b-tbody>` component (or in a second `<b-tbody>`
component), and set a role of `columnheader` on the child `<b-th>` cells, and use Bootstrap v4
[responsive display utility classes](/docs/reference/utility-classes) to hide the extra row (or
`<b-tbody>`) above a certain breakpoint when the table is no longer visually stacked (the breakpoint
should match the stacked table breakpoint you have set), i.e. `<b-tr class="d-md-none">` would hide
the row on medium and wider screens, while `<b-tbody class="d-md-none">` would hide the row group on
medium and wider screens.
**Note:** stacked mode with `<b-table-simple>` requires that you use the BootstrapVue
[table helper components](#table-helper-components). Use of the regular `<tbody>`, `<tr>`, `<td>`
and `<th>` element tags will not work as expected, nor will they automatically apply any of the
required accessibility attributes.
### Simple tables and sticky columns
Sticky columns are supported with `<b-table-simple>`, but you will need to set the `sticky-column`
prop on each table cell (in the `thead`, `tbody`, and `tfoot` row groups) in the column that is to
be sticky. For example:
```html
<b-table-simple responsive>
<b-thead>
<b-tr>
<b-th sticky-column>Sticky Column Header</b-th>
<b-th>Heading 1</b-th>
<b-th>Heading 2</b-th>
<b-th>Heading 3</b-th>
<b-th>Heading 4</b-th>
</b-tr>
</b-thead>
<b-tbody>
<b-tr>
<b-th sticky-column>Sticky Column Row Header</b-th>
<b-td>Cell</b-td>
<b-td>Cell</b-td>
<b-td>Cell</b-td>
<b-td>Cell</b-td>
</b-tr>
<b-tr>
<b-th sticky-column>Sticky Column Row Header</b-th>
<b-td>Cell</b-td>
<b-td>Cell</b-td>
<b-td>Cell</b-td>
<b-td>Cell</b-td>
</b-tr>
</b-tbody>
<b-tfoot>
<b-tr>
<b-th sticky-column>Sticky Column Footer</b-th>
<b-th>Heading 1</b-th>
<b-th>Heading 2</b-th>
<b-th>Heading 3</b-th>
<b-th>Heading 4</b-th>
</b-tr>
</b-tfoot>
</b-table-responsive>
```
As with `<b-table>` and `<b-table-lite>`, sticky columns are not supported when the `stacked` prop
is set on `<b-table-simple>`.
### Table simple as a plugin
The `TablePlugin` includes `<b-table-simple>` and all of the helper components. For convenience,
BootstrapVue also provides a `TableSimplePlugin` which installs `<b-table-simple>` and all of the
helper components. `TableSimplePlugin` is available as a top level named export.
## Table helper components
BootstrapVue provides additional helper child components when using `<b-table-simple>`, or the named
slots `top-row`, `bottom-row`, `thead-top`, and `custom-foot` (all of which accept table child
elements). The helper components are as follows:
- `b-tbody` (`<b-table-simple>` only)
- `b-thead` (`<b-table-simple>` only)
- `b-tfoot` (`<b-table-simple>` only)
- `b-tr`
- `b-td`
- `b-th`
These components are optimized to handle converting variants to the appropriate classes (such as
handling table `dark` mode), and automatically applying certain accessibility attributes (i.e.
`role`s and `scope`s). They also can generate the stacked table, and sticky header and column,
markup. Components `<b-table>` and `<b-table-lite>` use these helper components internally.
In the [Simple tables](#simple-tables) example, we are using the helper components `<b-thead>`,
`<b-tbody>`, `<b-tr>`, `<b-th>`, `<b-tr>` and `<b-tfoot>`. While you can use regular table child
elements (i.e. `<tbody>`, `<tr>`, `<td>`, etc.) within `<b-table-simple>`, and the named slots
`top-row`, `bottom-row`, and `thead-top`, it is recommended to use these BootstrapVue table `<b-t*>`
helper components. Note that there are no helper components for `<caption>`, `<colgroup>` or
`<col>`, so you may these three HTML5 elements directly in `<b-table-simple>`.
- Table helper components `<b-tr>`, `<b-td>` and `<b-th>` all accept a `variant` prop, which will
apply one of the Bootstrap theme colors (custom theme colors are supported via
[theming](/docs/reference/theming).) and will automatically adjust to use the correct variant
class based on the table's `dark` mode.
- The helper components `<b-thead>`, `<b-tfoot>` accept a `head-variant` and `foot-variant` prop
respectively. Supported values are `'dark'`, `'light'` or `null` (`null` uses the default table
background). These variants also control the text color (light text for `'dark'` variant, and dark
text for the `'light'` variant).
- Accessibility attributes `role` and `scope` are automatically set on `<b-th>` and `<b-td>`
components based on their location (thead, tbody, or tfoot) and their `rowspan` or `colspan`
props. You can override the automatic `scope` and `role` values by setting the appropriate
attribute on the helper component.
- For `<b-tbody>`, `<b-thead>`, and `<b-tfoot>` helper components, the appropriate default `role` of
`'rowgroup'` will be applied, unless you override the role by supplying a `role` attribute.
- For the `<b-tr>` helper component, the appropriate default `role` of `'row'` will be applied,
unless you override the role by supplying a `role` attribute. `<b-tr>` does not add a `scope`.
- The `<b-tbody>` element supports rendering a Vue `<transition-group>` when either, or both, of the
`tbody-transition-props` and `tbody-transition-handlers` props are used. See the
[Table body transition support](#table-body-transition-support) section for more details.
## Accessibility
The `<b-table>` and `<b-table-lite>` components, when using specific features, will attempt to
provide the best accessibility markup possible.
When using `<b-table-simple>` with the helper table components, elements will have the appropriate
roles applied by default, of which you can optionally override. When using click handlers on the
`<b-table-simple>` helper components, you will need to apply appropriate `aria-*` attributes, and
set `tabindex="0"` to make the click actions accessible to screen reader and keyboard-only users.
You should also listen for `@keydown.enter.prevent` to handle users pressing <kbd>Enter</kbd> to
trigger your click on cells or rows (required for accessibility for keyboard-only users).
### Heading accessibility
When a column (field) is sortable (`<b-table>` only) or there is a `head-clicked` listener
registered (`<b-table>` and `<b-table-lite>`), the header (and footer) `<th>` cells will be placed
into the document tab sequence (via `tabindex="0"`) for accessibility by keyboard-only and screen
reader users, so that the user may trigger a click (by pressing <kbd>Enter</kbd> on the header
cells.
### Data row accessibility
When the table is in `selectable` mode (`<b-table>` only, and prop `no-select-on-click` is not set),
or if there is a `row-clicked` event listener registered (`<b-table>` and `<b-table-lite>`), all
data item rows (`<tr>` elements) will be placed into the document tab sequence (via `tabindex="0"`)
to allow keyboard-only and screen reader users the ability to click the rows by pressing
<kbd>Enter</kbd> or <kbd>Space</kbd>.
When the table items rows are placed in the document tab sequence (`<b-table>` and
`<b-table-lite>`), they will also support basic keyboard navigation when focused:
- <kbd>Down</kbd> will move to the next row
- <kbd>Up</kbd> will move to the previous row
- <kbd>End</kbd> or <kbd>Down</kbd>+<kbd>Shift</kbd> will move to the last row
- <kbd>Home</kbd> or <kbd>Up</kbd>+<kbd>Shift</kbd> will move to the first row
- <kbd>Enter</kbd> or <kbd>Space</kbd> to click the row.
### Row event accessibility
Note the following row based events/actions (available with `<b-table>` and `<b-table-lite>`) are
not considered accessible, and should only be used if the functionality is non critical or can be
provided via other means:
- `row-dblclicked`
- `row-contextmenu`
- `row-hovered`
- `row-unhovered`
- `row-middle-clicked`
Note that the `row-middle-clicked` event is not supported in all browsers (i.e. IE, Safari and most
mobile browsers). When listening for `row-middle-clicked` events originating on elements that do not
support input or navigation, you will often want to explicitly prevent other default actions mapped
to the down action of the middle mouse button. On Windows this is usually autoscroll, and on macOS
and Linux this is usually clipboard paste. This can be done by preventing the default behaviour of
the `mousedown` or `pointerdown` event.
Additionally, you may need to avoid opening a default system or browser context menu after a right
click. Due to timing differences between operating systems, this too is not a preventable default
behaviour of `row-middle-clicked`. Instead, this can be done by preventing the default behaviour of
the `row-contextmenu` event.
It is recommended you test your app in as many browser and device variants as possible to ensure
your app handles the various inconsistencies with events.
## Complete example
```html
<template>
<b-container fluid>
<!-- User Interface controls -->
<b-row>
<b-col lg="6" class="my-1">
<b-form-group
label="Sort"
label-for="sort-by-select"
label-cols-sm="3"
label-align-sm="right"
label-size="sm"
class="mb-0"
v-slot="{ ariaDescribedby }"
>
<b-input-group size="sm">
<b-form-select
id="sort-by-select"
v-model="sortBy"
:options="sortOptions"
:aria-describedby="ariaDescribedby"
class="w-75"
>
<template #first>
<option value="">-- none --</option>
</template>
</b-form-select>
<b-form-select
v-model="sortDesc"
:disabled="!sortBy"
:aria-describedby="ariaDescribedby"
size="sm"
class="w-25"
>
<option :value="false">Asc</option>
<option :value="true">Desc</option>
</b-form-select>
</b-input-group>
</b-form-group>
</b-col>
<b-col lg="6" class="my-1">
<b-form-group
label="Initial sort"
label-for="initial-sort-select"
label-cols-sm="3"
label-align-sm="right"
label-size="sm"
class="mb-0"
>
<b-form-select
id="initial-sort-select"
v-model="sortDirection"
:options="['asc', 'desc', 'last']"
size="sm"
></b-form-select>
</b-form-group>
</b-col>
<b-col lg="6" class="my-1">
<b-form-group
label="Filter"
label-for="filter-input"
label-cols-sm="3"
label-align-sm="right"
label-size="sm"
class="mb-0"
>
<b-input-group size="sm">
<b-form-input
id="filter-input"
v-model="filter"
type="search"
placeholder="Type to Search"
></b-form-input>
<b-input-group-append>
<b-button :disabled="!filter" @click="filter = ''">Clear</b-button>
</b-input-group-append>
</b-input-group>
</b-form-group>
</b-col>
<b-col lg="6" class="my-1">
<b-form-group
v-model="sortDirection"
label="Filter On"
description="Leave all unchecked to filter on all data"
label-cols-sm="3"
label-align-sm="right"
label-size="sm"
class="mb-0"
v-slot="{ ariaDescribedby }"
>
<b-form-checkbox-group
v-model="filterOn"
:aria-describedby="ariaDescribedby"
class="mt-1"
>
<b-form-checkbox value="name">Name</b-form-checkbox>
<b-form-checkbox value="age">Age</b-form-checkbox>
<b-form-checkbox value="isActive">Active</b-form-checkbox>
</b-form-checkbox-group>
</b-form-group>
</b-col>
<b-col sm="5" md="6" class="my-1">
<b-form-group
label="Per page"
label-for="per-page-select"
label-cols-sm="6"
label-cols-md="4"
label-cols-lg="3"
label-align-sm="right"
label-size="sm"
class="mb-0"
>
<b-form-select
id="per-page-select"
v-model="perPage"
:options="pageOptions"
size="sm"
></b-form-select>
</b-form-group>
</b-col>
<b-col sm="7" md="6" class="my-1">
<b-pagination
v-model="currentPage"
:total-rows="totalRows"
:per-page="perPage"
align="fill"
size="sm"
class="my-0"
></b-pagination>
</b-col>
</b-row>
<!-- Main table element -->
<b-table
:items="items"
:fields="fields"
:current-page="currentPage"
:per-page="perPage"
:filter="filter"
:filter-included-fields="filterOn"
:sort-by.sync="sortBy"
:sort-desc.sync="sortDesc"
:sort-direction="sortDirection"
stacked="md"
show-empty
small
@filtered="onFiltered"
>
<template #cell(name)="row">
{{ row.value.first }} {{ row.value.last }}
</template>
<template #cell(actions)="row">
<b-button size="sm" @click="info(row.item, row.index, $event.target)" class="mr-1">
Info modal
</b-button>
<b-button size="sm" @click="row.toggleDetails">
{{ row.detailsShowing ? 'Hide' : 'Show' }} Details
</b-button>
</template>
<template #row-details="row">
<b-card>
<ul>
<li v-for="(value, key) in row.item" :key="key">{{ key }}: {{ value }}</li>
</ul>
</b-card>
</template>
</b-table>
<!-- Info modal -->
<b-modal :id="infoModal.id" :title="infoModal.title" ok-only @hide="resetInfoModal">
<pre>{{ infoModal.content }}</pre>
</b-modal>
</b-container>
</template>
<script>
export default {
data() {
return {
items: [
{ isActive: true, age: 40, name: { first: 'Dickerson', last: 'Macdonald' } },
{ isActive: false, age: 21, name: { first: 'Larsen', last: 'Shaw' } },
{
isActive: false,
age: 9,
name: { first: 'Mini', last: 'Navarro' },
_rowVariant: 'success'
},
{ isActive: false, age: 89, name: { first: 'Geneva', last: 'Wilson' } },
{ isActive: true, age: 38, name: { first: 'Jami', last: 'Carney' } },
{ isActive: false, age: 27, name: { first: 'Essie', last: 'Dunlap' } },
{ isActive: true, age: 40, name: { first: 'Thor', last: 'Macdonald' } },
{
isActive: true,
age: 87,
name: { first: 'Larsen', last: 'Shaw' },
_cellVariants: { age: 'danger', isActive: 'warning' }
},
{ isActive: false, age: 26, name: { first: 'Mitzi', last: 'Navarro' } },
{ isActive: false, age: 22, name: { first: 'Genevieve', last: 'Wilson' } },
{ isActive: true, age: 38, name: { first: 'John', last: 'Carney' } },
{ isActive: false, age: 29, name: { first: 'Dick', last: 'Dunlap' } }
],
fields: [
{ key: 'name', label: 'Person full name', sortable: true, sortDirection: 'desc' },
{ key: 'age', label: 'Person age', sortable: true, class: 'text-center' },
{
key: 'isActive',
label: 'Is Active',
formatter: (value, key, item) => {
return value ? 'Yes' : 'No'
},
sortable: true,
sortByFormatted: true,
filterByFormatted: true
},
{ key: 'actions', label: 'Actions' }
],
totalRows: 1,
currentPage: 1,
perPage: 5,
pageOptions: [5, 10, 15, { value: 100, text: "Show a lot" }],
sortBy: '',
sortDesc: false,
sortDirection: 'asc',
filter: null,
filterOn: [],
infoModal: {
id: 'info-modal',
title: '',
content: ''
}
}
},
computed: {
sortOptions() {
// Create an options list from our fields
return this.fields
.filter(f => f.sortable)
.map(f => {
return { text: f.label, value: f.key }
})
}
},
mounted() {
// Set the initial number of items
this.totalRows = this.items.length
},
methods: {
info(item, index, button) {
this.infoModal.title = `Row index: ${index}`
this.infoModal.content = JSON.stringify(item, null, 2)
this.$root.$emit('bv::show::modal', this.infoModal.id, button)
},
resetInfoModal() {
this.infoModal.title = ''
this.infoModal.content = ''
},
onFiltered(filteredItems) {
// Trigger pagination to update the number of buttons/pages due to filtering
this.totalRows = filteredItems.length
this.currentPage = 1
}
}
}
</script>
<!-- b-table-complete.vue -->
```
<!-- Component reference added automatically from component package.json -->