Table

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> and <b-table-simple>.

Component reference

<b-table>

Properties

All property default values are globally configurable.

Property
(Click to sort ascending)
Type
(Click to sort ascending)
Default
Description
api-url
StringPass through prop. Passed as part of the context object sent to the items provider function
bordered
BooleanfalseAdds borders to all the cells and headers
borderless
BooleanfalseRemoves all borders from cells
busy
BooleanfalseWhen set, forces the table into the busy state.Automatically set when an items provider function is being called
caption
StringText string to place in the caption element
caption-html
Use with caution
StringHTML string to place in the caption element
caption-top
BooleanfalseVisually place the table caption above the table. Default is below
current-page
Number or String1The current page number to display when the table is paginated. Starting from 1 and up
dark
BooleanfalsePlaces the table in dark mode
details-td-class
v2.1.0+
Array or Object or StringCSS class (or classes) to apply to the row details' `td` element for the row-details slot
empty-filtered-html
Use with caution
StringHTML string to show when the table has no items to show due to filtering
empty-filtered-text
String'There are no records matching your request'Text string to show when the table has no items to show due to filtering
empty-html
Use with caution
StringHTML string to show when the table has no items to show
empty-text
String'There are no records to show'Text string to show when the table has no items to show
fields
ArraynullArray of field names or array of field definition objects
filter
Array or Object or String or RegExpCriteria for filtering. Internal filtering supports only string or RegExpr criteria
filter-debounce
v2.0.0+
Number or String0Time in milliseconds to debounce changes to the filter criteria before filtering the records
filter-function
FunctionReference to a function to use instead of the internal filtering function. Refer to the docs for details
filter-ignored-fields
Array[]Array of top level fields to ignore when filtering the item data
filter-included-fields
Array[]Array of fields to include when filtering. Overrides filter-ignore-fields
fixed
BooleanfalseMakes all columns equal width (fixed layout table). Will speed up rendering for large tables. Column widths can be set via CSS or colgroup
foot-clone
BooleanfalseEnable the footer of the table, and clone the header content by default
foot-row-variant
v2.1.0+
StringApply a Bootstrap theme color variant to the tr element in the tfoot. Falls back to head-row-variant
foot-variant
StringFooter variant: 'light' or 'dark', or unset. May take precedence over foot-row-variant
head-row-variant
v2.1.0+
StringApply a Bootstrap theme color variant to the tr element in the thead
head-variant
StringHeader variant: 'light' or 'dark', or unset. May take precedence over head-row-variant
hover
BooleanfalseEnables hover styling on rows
id
StringUsed to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
items
Array or Function[]Array of items to display, or an items provider function reference. Refer to the docs for details
label-sort-asc
String'Click to sort ascending'Hidden string to place in the header cell when clicking the cell will change the sort direction to ascending
label-sort-clear
String'Click to clear sorting'Hidden string to place in the header cell when clicking the cell will clear the current sorting direction
label-sort-desc
String'Click to sort descending'Hidden string to place in the header cell when clicking the cell will change the sort direction to descending
no-border-collapse
v2.0.0+
BooleanfalseDisable's the collapsing of table borders. Useful when table has sticky headers or columns
no-footer-sorting
BooleanfalseWhen the build in formatter is used, setting this prop will disable the sorting ability in the footer
no-local-sorting
BooleanfalseDisabled the internal sorting routine, and expects the user to provde the items sorted. Sorting controls will still be available
no-provider-filtering
BooleanfalseWhen set, uses internal filtering to pagination the data. Otherwise the provider is expected to perform the filtering
no-provider-paging
BooleanfalseWhen set, uses internal paging to pagination the data. Otherwise the items provider is expected to perform the paging
no-provider-sorting
BooleanfalseWhen set, uses internal sorting to sort the data. Otherwise the items provider is expected to perform the sorting
no-select-on-click
v2.1.0+
BooleanfalseDisables row selection via click events. Row selection will be only available programmatically
no-sort-reset
BooleanfalseWhen a table is sortable, clicking on any non-sortable column heading will clear the current sort values. Set this prop to disable this feature
outlined
BooleanfalseAdds an outline border to the table element
per-page
Number or String0Number of rows to show per page. Set to 0 to disable pagination
primary-key
StringName of a table field that contains a guaranteed unique value per row. Needed for tbody transition support, and also speeds up table rendering
responsive
Boolean or StringfalseMakes the table responsive in width, adding a horizontal scrollbar. Set to true for always responsive or set to one of the breakpoints to switch from responsive to normal: 'sm', 'md', 'lg', 'xl'
select-mode
String'multi'The selectable mode for the table when 'selectable' is set. Possible values: 'single', 'multi' or 'range'
selectable
BooleanfalseWhen set, places the table body rows in selectable mode
selected-variant
String'active'Bootstrap color theme variant to set selected rows to. Use any of the standard Bootstrap theme color variants, or the special table row variant 'active' (default). Set to an empty string to not use a variant
show-empty
BooleanfalseWhen enabled, and there are no item records to show, shows a message that there are no rows to show
small
BooleanfalseRenders the table with smaller cell padding
sort-by
StringField name that is currently being sorted. Set to null to clear sorting. Syncable with the .sync prop modifier
sort-compare
FunctionA reference to a function for sort-comparing two rows of data. Defaults to the internal sort compare routine. See docs for details
sort-compare-locale
Array or StringThe locale string (or array of locale string) that specified the language when sorting. See docs for details
sort-compare-options
Object{ 'numeric': true }An object containing sort configuration for the 'String.prototype.sortLocale' method. See docs for details
sort-desc
BooleanfalseSet to true to sort the column in descending order. Syncable with the .sync prop modifier
sort-direction
String'asc'The initial sorting direction to sort an unsorted column by: 'asc', 'desc', or 'last' (to use the previous sort direction)
sort-icon-left
BooleanfalsePositions the sort control to the left of the header text. Default is on the right of the header text
sort-null-last
BooleanfalseWhen sorting, null and undefined values will be sorted first (or last, depending on 'sort-desc'). Set this prop to sort null values last. Only applicable to internal sorting
stacked
Boolean or StringfalsePlace the table in stacked mode. Set to true for always stacked, or set to one of the breakpoints to switch from stacked to normal: 'sm', 'md', 'lg', 'xl'
sticky-header
Boolean or StringfalseMakes the table header sticky. Set to true for a maximum height 300px tall table, or set to any valid CSS hight (including units)
striped
BooleanfalseApplies striping to the tbody rows
table-class
Array or Object or StringCSS class (or classes) to apply to the table element
table-variant
StringApply a Bootstrap theme color variant to the entire table
tbody-class
Array or Object or StringCSS class (or classes) to apply to the tbody element
tbody-tr-attr
v2.2.0+
Object or FunctionAttributes to be added to each tr in the tbody, or a function returning such attributes (see docs for details)
tbody-tr-class
Array or Object or String or FunctionCSS class (or classes) to apply to the tr element in the tbody. Can be a function that returns a class (see docs for details)
tbody-transition-handlers
ObjectVue 'transition-group' event handlers. When provided will make the tbody a Vue 'transition-group' component
tbody-transition-props
ObjectVue 'transition-group' properties. When provided will make the tbody a Vue 'transition-group' component
tfoot-class
Array or Object or StringCSS class (or classes) to apply to the tfoot element
tfoot-tr-class
Array or Object or StringCSS class (or classes) to apply to the tr element in the tfoot
thead-class
Array or Object or StringCSS class (or classes) to apply to the thead element
thead-tr-class
Array or Object or StringCSS class (or classes) to apply to the tr element in the thead
value
v-model
Array[]Currently displayed row data. Read-only. Do not set a value on this prop

Caution: Props that support HTML strings (*-html) can be vulnerable to Cross Site Scripting (XSS) attacks when passed raw user supplied values. You must properly sanitize the user input first!

v-model

Property
Event
valueinput

Slots

Name
(Click to sort ascending)
Scoped
Description
bottom-row Fixed bottom row slot for user supplied B-TD cells. Optionally Scoped
cell() Default scoped slot for custom data rendering of field data. See docs for scoped data
cell({key}) Scoped slot for custom data rendering of field data. '{key}' is the field's key name. See docs for scoped data
custom-foot Custom footer content slot for user supplied B-TR, B-TH, B-TD. Optionally Scoped
empty Content to display when no items are present in the `items` array. Optionally scoped
emptyfiltered Content to display when no items are present in the filtered `items` array. Optionally scoped
foot() Default scoped slot for custom rendering of field footer. See docs for scoped footer
foot({key}) Scoped slot for custom rendering of field footer. '{key}' is the field's key name. See docs for scoped footer
head() Default scoped slot for custom rendering of field header. See docs for scoped header
head({key}) Scoped slot for custom rendering of field header. '{key}' is the field's key name. See docs for scoped header
row-details Scoped slot for optional rendering additional record details. See docs for Row details support
table-busy NoOptional slot to place loading message when table is in the busy state
table-caption NoContent to display in the table's caption element
table-colgroup Slot to place custom colgroup and col elements. Optionally scoped
thead-top Slot above the column headers in the `thead` element for user-supplied B-TR's with B-TH/B-TD. Optionally scoped
top-row Fixed top row slot for user supplied B-TD cells. Optionally scoped

Events

Event
(Click to sort ascending)
Arguments
Description
context-changed
  1. ctx - Table state context object. See docs
Emitted whenever the table state context has changed
filtered
  1. filteredItems - Array of items after filtering (before local pagination occurs)
Emitted when local filtering causes a change in the number of items
head-clicked
  1. key - Column key clicked (field name)
  2. field - Field definition object
  3. event - Native event object
  4. isFooter - 'True' if this event originated from clicking on the footer cell
Emitted when a header or footer cell is clicked. Not applicable for 'custom-foot' slot
refreshed Emitted when the items provider function has returned data
row-clicked
  1. item - Item data of the row being clicked
  2. index - Index of the row being clicked
  3. event - Native event object
Emitted when a row is clicked
row-contextmenu
  1. item - Item data of the row being right clicked
  2. index - Index of the row being right clicked
  3. event - Native event object
Emitted when a row is right clicked
row-dblclicked
  1. item - Item data of the row being double clicked
  2. index - Index of the row being double clicked
  3. event - Native event object
Emitted when a row is double clicked
row-hovered
  1. item - Item data of the row being hovered
  2. index - Index of the row being hovered
  3. event - Native event object
Emitted when a row is hovered
row-middle-clicked
  1. item - Item data of the row being middle clicked
  2. index - Index of the row being middle clicked
  3. event - Native event object
Emitted when a row is middle clicked
row-selected
  1. rows - Array of the row items that are selected
Emitted when a row or rows have been selected or unselected
row-unhovered
  1. item - Item data of the row being unhovered
  2. index - Index of the row being unhovered
  3. event - Native event object
Emitted when a row is unhovered
sort-changed
  1. ctx - Table state context object. See docs
Emitted when the sorting on the table has changed

$root event listeners

You can control <b-table> by emitting the following events on $root:

Event
Arguments
Description
bv::refresh::table

id - Table ID to refresh data

Refresh data of a specific table when this event is emitted on $root

<b-table-lite>

Properties

All property default values are globally configurable.

Property
(Click to sort ascending)
Type
(Click to sort ascending)
Default
Description
bordered
BooleanfalseAdds borders to all the cells and headers
borderless
BooleanfalseRemoves all borders from cells
caption
StringText string to place in the caption element
caption-html
Use with caution
StringHTML string to place in the caption element
caption-top
BooleanfalseVisually place the table caption above the table. Default is below
dark
BooleanfalsePlaces the table in dark mode
details-td-class
v2.1.0+
Array or Object or StringCSS class (or classes) to apply to the td element in the details row
fields
ArraynullArray of field names or array of field definition objects
fixed
BooleanfalseMakes all columns equal width (fixed layout table). Will speed up rendering for large tables. Column widths can be set via CSS or colgroup
foot-clone
BooleanfalseEnable to the footer of the table, and clone the header content by default
foot-row-variant
v2.1.0+
StringApply a Bootstrap theme color variant to the tr element in the tfoot. Falls back to head-row-variant
foot-variant
StringFooter variant: 'light' or 'dark', or unset. May take precedence over foot-row-variant
head-row-variant
v2.1.0+
StringApply a Bootstrap theme color variant to the tr element in the thead
head-variant
StringHeader variant: 'light' or 'dark', or unset. May take precedence over head-row-variant
hover
BooleanfalseEnables hover styling on rows
id
StringUsed to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
items
Array[]Array of items to display
no-border-collapse
v2.0.0+
BooleanfalseDisable's the collapsing of table borders. Useful when table has sticky headers or columns
outlined
BooleanfalseAdds an outline border to the table element
primary-key
StringName of a table field that contains a guaranteed unique value per row. Needed for tbody transition support, and also speeds up table rendering
responsive
Boolean or StringfalseMakes the table responsive in width, adding a horizontal scrollbar. Set to true for always responsive or set to one of the breakpoints to switch from responsive to normal: 'sm', 'md', 'lg', 'xl'
small
BooleanfalseRenders the table with smaller cell padding
stacked
Boolean or StringfalsePlace the table in stacked mode. Set to true for always stacked, or set to one of the breakpoints to switch from stacked to normal: 'sm', 'md', 'lg', 'xl'
sticky-header
Boolean or StringfalseMakes the table header sticky. Set to true for a maximum height 300px tall table, or set to any valid CSS hight (including units)
striped
BooleanfalseApplies striping to the tbody rows
table-class
Array or Object or StringCSS class (or classes) to apply to the table element
table-variant
StringApply a Bootstrap theme color variant to the entire table
tbody-class
Array or Object or StringCSS class (or classes) to apply to the tbody element
tbody-tr-attr
v2.2.0+
Object or FunctionAttributes to be added to each tr in the tbody, or a function returning such attributes (see docs for details)
tbody-tr-class
Array or Object or String or FunctionCSS class (or classes) to apply to the tr element in the tbody. Can be a function that returns a class (see docs for details)
tbody-transition-handlers
ObjectVue 'transition-group' event handlers. When provided will make the tbody a Vue 'transition-group' component
tbody-transition-props
ObjectVue 'transition-group' properties. When provided will make the tbody a Vue 'transition-group' component
tfoot-class
Array or Object or StringCSS class (or classes) to apply to the tfoot element
tfoot-tr-class
Array or Object or StringCSS class (or classes) to apply to the tr element in the tfoot
thead-class
Array or Object or StringCSS class (or classes) to apply to the thead element
thead-tr-class
Array or Object or StringCSS class (or classes) to apply to the tr element in the thead
value
v-model
Array[]Currently displayed row data. Read-only. Do not set a value on this prop

Caution: Props that support HTML strings (*-html) can be vulnerable to Cross Site Scripting (XSS) attacks when passed raw user supplied values. You must properly sanitize the user input first!

v-model

Property
Event
valueinput

Slots

Name
(Click to sort ascending)
Scoped
Description
cell() Default scoped slot for custom data rendering of field data
cell({key}) Scoped slot for custom data rendering of field data. '{key}' is the field's key name
custom-foot Custom footer content slot for user supplied B-TR's with B-TH/B-TD. Optionally Scoped
foot() Default scoped slot for custom rendering of field footer
foot({key}) Scoped slot for custom rendering of field footer. '{key}' is the field's key name
head() Default scoped slot for custom rendering of field header
head({key}) Scoped slot for custom rendering of field header. '{key}' is the field's key name
row-details Scoped slot for optional rendering additional record details. See docs for Row details support
table-caption NoContent to display in the table's caption element
table-colgroup Slot to place custom colgroup and col elements. Optionally scoped
thead-top Slot above the column headers in the `thead` element for user-supplied B-TR with B-TH/B-TD. Optionally scoped

Events

Event
Arguments
Description
head-clicked
  1. key - Column key clicked (field name)
  2. field - Field definition object
  3. event - Native event object
  4. isFooter - 'True' if this event originated from clicking on the footer cell
Emitted when a header or footer cell is clicked. Not applicable for 'custom-foot' slot
row-clicked
  1. item - Item data of the row being clicked
  2. index - Index of the row being clicked
  3. event - Native event object
Emitted when a row is clicked
row-contextmenu
  1. item - Item data of the row being right clicked
  2. index - Index of the row being right clicked
  3. event - Native event object
Emitted when a row is right clicked
row-dblclicked
  1. item - Item data of the row being double clicked
  2. index - Index of the row being double clicked
  3. event - Native event object
Emitted when a row is double clicked
row-hovered
  1. item - Item data of the row being hovered
  2. index - Index of the row being hovered
  3. event - Native event object
Emitted when a row is hovered
row-middle-clicked
  1. item - Item data of the row being middle clicked
  2. index - Index of the row being middle clicked
  3. event - Native event object
Emitted when a row is middle clicked
row-unhovered
  1. item - Item data of the row being unhovered
  2. index - Index of the row being unhovered
  3. event - Native event object
Emitted when a row is unhovered

<b-table-simple>

Properties

All property default values are globally configurable.

Property
(Click to sort ascending)
Type
(Click to sort ascending)
Default
Description
bordered
BooleanfalseAdds borders to all the cells and headers
borderless
BooleanfalseRemoves all borders from cells
caption-top
BooleanfalseVisually place the table caption above the table. Default is below
dark
BooleanfalsePlaces the table in dark mode
fixed
BooleanfalseMakes all columns equal width (fixed layout table). Will speed up rendering for large tables. Column widths can be set via CSS or colgroup
hover
BooleanfalseEnables hover styling on rows
id
StringUsed to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
no-border-collapse
v2.0.0+
BooleanfalseDisable's the collapsing of table borders. Useful when table has sticky headers or columns
outlined
BooleanfalseAdds an outline border to the table element
responsive
Boolean or StringfalseMakes the table responsive in width, adding a horizontal scrollbar. Set to true for always responsive or set to one of the breakpoints to switch from responsive to normal: 'sm', 'md', 'lg', 'xl'
small
BooleanfalseRenders the table with smaller cell padding
stacked
Boolean or StringfalsePlace the table in stacked mode. Set to true for always stacked, or set to one of the breakpoints to switch from stacked to normal: 'sm', 'md', 'lg', 'xl'
sticky-header
Boolean or StringfalseMakes the table header sticky. Set to true for a maximum height 300px tall table, or set to any valid CSS hight (including units)
striped
BooleanfalseApplies striping to the tbody rows
table-class
Array or Object or StringCSS class (or classes) to apply to the table element
table-variant
StringApply a Bootstrap theme color variant to the entire table

Slots

Name
Description
default Content to place in the table

<b-tbody>

Properties

All property default values are globally configurable.

Property
Type
Default
Description
tbody-transition-handlers
ObjectVue 'transition-group' event handlers. When provided will make the tbody a Vue 'transition-group' component
tbody-transition-props
ObjectVue 'transition-group' properties. When provided will make the tbody a Vue 'transition-group' component

Slots

Name
Description
default Content to place in the tbody

<b-thead>

Properties

All property default values are globally configurable.

Property
Type
Default
Description
head-variant
StringHeader variant: 'light' or 'dark', or unset

Slots

Name
Description
default Content to place in the thead

<b-tfoot>

Properties

All property default values are globally configurable.

Property
Type
Default
Description
foot-variant
StringFooter variant: 'light' or 'dark', or unset

Slots

Name
Description
default Content to place in the tfoot

<b-tr>

Properties

All property default values are globally configurable.

Property
Type
Default
Description
variant
StringApplies one of the Bootstrap theme color variants to the component

Slots

Name
Description
default Content to place in the tr

<b-td>

Properties

All property default values are globally configurable.

Property
Type
Default
Description
colspan
Number or StringnullNumber of columns this cell spans
rowspan
Number or StringnullNumber of rows this cell spans
stacked-heading
StringHeading for the cell when in stacked mode. Only applicable to cells in the 'tbody' element
sticky-column
BooleanfalseIf this will be a sticky colum. Must be set on all cells in this column. table must be in sticky-header or responsive mode to work
variant
StringApplies one of the Bootstrap theme color variants to the component

Slots

Name
Description
default Content to place in the td

<b-th>

Properties

All property default values are globally configurable.

Property
Type
Default
Description
colspan
Number or StringnullNumber of columns this cell spans
rowspan
Number or StringnullNumber of rows this cell spans
stacked-heading
StringHeading for the cell when in stacked mode. Only applicable to cells in the 'tbody' element
sticky-column
BooleanfalseIf this will be a sticky colum. Must be set on all cells in this column. table must be in sticky-header or responsive mode to work
variant
StringApplies one of the Bootstrap theme color variants to the component

Importing individual components

You can import individual components into your project via the following named exports:

Component
Named Export
Import Path
<b-table>BTablebootstrap-vue
<b-table-lite>BTableLitebootstrap-vue
<b-table-simple>BTableSimplebootstrap-vue
<b-tbody>BTbodybootstrap-vue
<b-thead>BTheadbootstrap-vue
<b-tfoot>BTfootbootstrap-vue
<b-tr>BTrbootstrap-vue
<b-td>BTdbootstrap-vue
<b-th>BThbootstrap-vue

Example:

import { BTable } from 'bootstrap-vue'
Vue.component('b-table', BTable)

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export
Import Path
TablePluginbootstrap-vue

This plugin also automatically includes the following plugins:

  • TableLitePlugin
  • TableSimplePlugin

Example:

import { TablePlugin } from 'bootstrap-vue'
Vue.use(TablePlugin)