docs/markdown/intro/README.md
Get started with BootstrapVue, based on the world's most popular framework - Bootstrap v{{ bootstrapVersionMajor }}, for building responsive, mobile-first sites using Vue.js.
v{{ vueVersionMinor }} is required, v{{ vueVersion }} is
recommendedv4.3.1 is required, v{{ bootstrapVersion }} is
recommendedv{{ popperVersionMinor }} is required for dropdowns (and
components based on dropdown), tooltips, and popovers. v{{ popperVersion }} is recommendedv{{ portalVueVersionMinor }} is required by
Toasts, v{{ portalVueVersion }} is recommendedCheck out what is new in BootstrapVue release v{{ version }}.
If you are migrating from a previous v2.0.0-rc.## release, please see the
v2.0.0 migration guide.
The online documentation comprises:
This BootstrapVue documentation assumes you are familiar with Vue and Bootstrap v{{ bootstrapVersionMajor }} CSS. Good starting points for these:
.vue filesIn many of the examples shown in BootstrapVue's documentation, you may see the use of CSS classes such as <code class="text-nowrap">ml-2</code>, <code class="text-nowrap">py-1</code>, etc. These are Bootstrap v{{bootstrapVersionMinor}} utility classes that help control padding, margins, positioning, and more. You can find information on these classes in the Utility Classes reference section.
Many of the examples in this documentation are live and can be edited in-place for an enhanced
learning experience (note some examples may not work in IE 11 due to use of ES6 JavaScript code in
the <template> sections).
BootstrapVue also provides an interactive playground where you can experiment with the various components and export your results to JSFiddle, CodePen, and/or CodeSandbox.
Bootstrap v{{bootstrapVersionMajor}} CSS employs a handful of important global styles and settings that you'll need to be aware of when using it, all of which are almost exclusively geared towards the normalization of cross browser styles. Refer to the following sub-sections for details.
Bootstrap requires the use of the HTML5 doctype. Without it, you may see some strange incomplete
styling.
<!doctype html>
<html lang="en">
...
</html>
Bootstrap is optimized for mobile devices first and then scales up components as necessary using CSS
media queries. To ensure proper rendering and touch zooming for all devices, add the responsive
viewport meta tag to your <head>.
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
For more straightforward sizing in CSS, the global box-sizing value is switched from content-box
to border-box. This ensures padding does not affect the final computed width of an element, but
it can cause problems with some third party software like Google Maps and Google Custom Search
Engine.
On the rare occasion you need to override it, use something like the following:
.selector-for-some-widget {
box-sizing: content-box;
}
With the above snippet, nested elements — including generated content via ::before and ::after —
will all inherit the specified box-sizing for that .selector-for-some-widget.
Learn more about box model and sizing at CSS Tricks.
For improved cross-browser rendering, Bootstrap v{{ bootstrapVersionMinor }} uses Reboot to correct inconsistencies across browsers and devices while providing slightly more opinionated resets to common <abbr title="Hyper Text markup Language">HTML</abbr> elements.
Most likely you are using module bundlers like Webpack,
Parcel or rollup.js, which makes it easy to
directly include the package into your project. To do this, use npm or yarn to get the latest
version of Vue.js, Bootstrap v4 and BootstrapVue:
# With npm
npm install vue bootstrap@4 bootstrap-vue
# With yarn
yarn add vue bootstrap@4 bootstrap-vue
Then, register BootstrapVue in your app entry point (typically app.js or main.js):
// app.js
import Vue from 'vue'
import { BootstrapVue, IconsPlugin } from 'bootstrap-vue'
// Import Bootstrap and BootstrapVue CSS files (order is important)
import 'bootstrap/dist/css/bootstrap.css'
import 'bootstrap-vue/dist/bootstrap-vue.css'
// Make BootstrapVue available throughout your project
Vue.use(BootstrapVue)
// Optionally install the BootstrapVue icon components plugin
Vue.use(IconsPlugin)
If you want to change Bootstrap's default styles (e.g. the $body-color), you have to use
Bootstrap's and BootstrapVue's scss files.
Create your own scss file (e.g. app.scss) containing both your custom definitions and
the 2 @import's at the end:
// app.scss
// Define variable defaults
$body-bg: #000;
$body-color: #111;
// Then import Bootstrap and BootstrapVue SCSS files (order is important)
@import 'node_modules/bootstrap/scss/bootstrap.scss';
@import 'node_modules/bootstrap-vue/src/index.scss';
Then import that single scss file into your project:
// app.js
import Vue from 'vue'
import { BootstrapVue } from 'bootstrap-vue'
import './app.scss'
Vue.use(BootstrapVue)
Do not import the individual SCSS files separately into your project, because variables and functions will fail to be shared between files.
For information on theming Bootstrap, check out the Theming reference section.
BootstrapVue and PortalVue require access to the global Vue reference (via
import Vue from 'vue').
Example: Vue alias for Vue CLI in vue.config.js
const path = require('path')
module.exports = {
chainWebpack: config => {
config.resolve.alias.set(
'vue$',
// If using the runtime only build
path.resolve(__dirname, 'node_modules/vue/dist/vue.runtime.esm.js')
// Or if using full build of Vue (runtime + compiler)
// path.resolve(__dirname, 'node_modules/vue/dist/vue.esm.js')
)
}
}
Example: Vue alias in webpack.config.js
module.exports = {
// ...
resolve: {
alias: {
// If using the runtime only build
vue$: 'vue/dist/vue.runtime.esm.js' // 'vue/dist/vue.runtime.common.js' for webpack 1
// Or if using full build of Vue (runtime + compiler)
// vue$: 'vue/dist/vue.esm.js' // 'vue/dist/vue.common.js' for webpack 1
}
}
}
Note: If your project has multiple webpack config files (i.e. webpack.config.js,
webpack.renderer.config.js, webpack.vendor.config.js, webpack.server.config.js,
webpack.client.config.js, etc.), you will need to set the appropriate alias in all of them.
See the Vue.js Guide for full details on setting up aliases for webpack, rollup.js, Parcel, etc.
Webpack and Parcel support prepending the scss modules with tilde paths (~) when importing from
a scss file:
// Webpack example
@import '~bootstrap';
@import '~bootstrap-vue';
// Parcel example
@import '~bootstrap/scss/bootstrap.scss';
@import '~bootstrap-vue/src/index.scss';
For more details how to configure asset loading and how modules are resolved, please consult the module bundlers documentation.
Notes:
When using a module bundler you can optionally import only specific components groups (plugins), components and/or directives. Note that tree shaking only applies to the JavaScript code and not CSS/SCSS.
<div class="alert alert-info"> <p class="mb-0"> <b>Note:</b> Optimal tree shaking only works when webpack 4 is in <a href="https://webpack.js.org/guides/tree-shaking"><code>production</code></a> mode and javascript minification is enabled. </p> </div>You can import component groups and directives as Vue plugins by importing from the bootstrap-vue:
// This imports all the layout components such as <b-container>, <b-row>, <b-col>:
import { LayoutPlugin } from 'bootstrap-vue'
Vue.use(LayoutPlugin)
// This imports <b-modal> as well as the v-b-modal directive as a plugin:
import { ModalPlugin } from 'bootstrap-vue'
Vue.use(ModalPlugin)
// This imports <b-card> along with all the <b-card-*> sub-components as a plugin:
import { CardPlugin } from 'bootstrap-vue'
Vue.use(CardPlugin)
// This imports directive v-b-scrollspy as a plugin:
import { VBScrollspyPlugin } from 'bootstrap-vue'
Vue.use(VBScrollspyPlugin)
// This imports the dropdown and table plugins
import { DropdownPlugin, TablePlugin } from 'bootstrap-vue'
Vue.use(DropdownPlugin)
Vue.use(TablePlugin)
When importing as plugins, all subcomponents and related directives are imported in most cases. i.e.
When importing <b-nav>, all the <nav-*> sub components are also included, as well all dropdown
sub components. Component shorthand aliases (if any) are also included in the plugin. Refer to the
component and directive documentation for details.
There are two additional helper plugins for providing the $bvModal and $bvToast injections (if
you are not using the ModalPlugin or ToastPlugin plugins) which are available for import from
'bootstrap-vue':
BVModalPlugin - provides the injection $bvModal for generating
message boxes.BVToastPlugin - provides the injection $bvToast for generating
on demand toasts.When importing multiple component group and/or directive group plugins, include all imports in a
single import statement for optimal tree shaking.
If you would like to only pull in a specific component or set of components, you can do this by directly importing those components.
To cherry pick a component/directive, start by importing it in the file where it is being used:
<!-- eslint-disable no-unused-vars -->// Place all imports from 'bootstrap-vue' in a single import
// statement for optimal bundle sizes
import { BModal, VBModal } from 'bootstrap-vue'
Then add it to your component definition:
<!-- eslint-disable no-undef -->Vue.component('MyComponent', {
components: { BModal },
// Note that Vue automatically prefixes directive names with `v-`
directives: { 'b-modal': VBModal }
// ...
})
Or register them globally:
<!-- eslint-disable no-undef -->Vue.component('BModal', BModal)
// Note that Vue automatically prefixes directive names with `v-`
Vue.directive('b-modal', VBModal)
Vue allows for various component and directive name syntaxes here, so feel free to utilize <samp>kebab-casing</samp> (shown), <samp>camelCasing</samp>, <samp>PascalCasing</samp>, and/or object property shorthand (components only).
When using module bundlers, they will usually default to using the esm/ modular build, which has
been pre-transpiled by Babel for our
supported browsers.
You can override the use of the esm/ build by aliasing 'bootstrap-vue' to use the BootstrapVue
source files, and whitelisting node_modules/bootstrap-vue/src/* for transpilation by your build
process, in your module bundler config. This will allow you to transpile BootstrapVue for your
target browsers/environments and potentially reduce bundle sizes (and will only include the babel
helper utils once) at the expense of slightly longer build times.
Example webpack.config.js for Babel transpilation:
module.exports = {
resolve: {
alias: {
// Alias for using source of BootstrapVue
'bootstrap-vue$': 'bootstrap-vue/src/index.js'
}
},
module: {
rules: [
{
test: /\.js$/,
// Exclude transpiling `node_modules`, except `bootstrap-vue/src`
exclude: /node_modules\/(?!bootstrap-vue\/src\/)/,
use: {
loader: 'babel-loader',
options: {
presets: ['env']
}
}
}
]
}
}
You may need to install babel-core, babel-loader, and babel-preset-env:
# If using npm
npm install babel-core babel-loader babel-preset-env --save-dev
# If using yarn
yarn add babel-core babel-loader babel-preset-env --dev
For more details see:
BootstrapVue provides a Nuxt.js module for easily importing BootstrapVue (or portions of BootstrapVue) into your Nuxt.js app.
Nuxt.js version <code>{{ nuxtVersion }}</code> (or greater) is recommended.
Install dependencies:
# With npm
npm install bootstrap-vue
# With yarn
yarn add bootstrap-vue
Add bootstrap-vue/nuxt to modules section of your nuxt.config.js file.
This will include both bootstrap.css and bootstrap-vue.css default pre-compiled CSS.
module.exports = {
modules: ['bootstrap-vue/nuxt']
}
Note that this will not install the Icons components. To see how to include icons via the Nuxt.js module, refer to the Icons section below.
If you are using custom Bootstrap SCSS, you can disable automatic inclusion of Bootstrap and
BootstrapVue pre-compiled CSS files by setting the following option(s) to false:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
bootstrapCSS: false, // Or `css: false`
bootstrapVueCSS: false // Or `bvCSS: false`
}
}
BootstrapVue's custom SCSS relies on Bootstrap SCSS variables and mixins, and any variable overrides you may have set. You can include Bootstrap and BootstrapVue SCSS in your project's custom SCSS file:
// custom.scss
// Custom Bootstrap variable overrides go first
$grid-breakpoints: (
xs: 0,
sm: 480px,
md: 640px,
lg: 992px,
xl: 1300px
);
$enable-rounded: false;
// Then include the following
@import 'bootstrap/scss/bootstrap.scss';
@import 'bootstrap-vue/src/index.scss';
// And define any of your custom or additional CSS/SCSS here,
// or via an @import
In your app main entry point include the single custom SCSS file (when using sass-loader):
// app.js
import 'custom.scss'
transformAssetUrls with Nuxt.jsThe BootstrapVue Nuxt plugin module will automatically add in the BootstrapVue specific
transformAssetUrls image src prop configuration for you.
If you wish to reduce your production bundle size because you only use a subset of the available
BootstrapVue plugins, you can configure the list of BootstrapVue componentPlugins or
directivePlugins you want to globally install in your Nuxt.js project. Note tree shaking only
applies to the JavaScript code and not CSS/SCSS.
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
componentPlugins: [
'LayoutPlugin',
'FormPlugin',
'FormCheckboxPlugin',
'FormInputPlugin',
'FormRadioPlugin',
'ToastPlugin',
'ModalPlugin'
],
directivePlugins: ['VBPopoverPlugin', 'VBTooltipPlugin', 'VBScrollspyPlugin']
}
}
There are two additional helper plugins for providing the $bvModal and $bvToast injections (if
you are not using the ModalPlugin or ToastPlugin plugins) that are available in the
componentPlugins option:
BVModalPlugin - provides the injection $bvModal for generating
message boxes.BVToastPlugin - provides the injection $bvToast for generating
on demand toasts.You can also optionally import individual components and/or directives, by configuring the list of
BootstrapVue components or directives you want to globally install in your Nuxt.js project.
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
components: ['BContainer', 'BRow', 'BCol', 'BFormInput', 'BButton', 'BTable', 'BModal'],
directives: ['VBModal', 'VBPopover', 'VBTooltip', 'VBScrollspy']
}
}
Feel free to mix and match plugin imports with individual component and directive imports.
Refer to the reference section at the bottom of each of the component and directive docs for details on the plugin names available (and which components and directives are included in each plugin) and component and/or directive import names.
Note that when importing individual components, any component aliases will not be available.
<div class="alert alert-info"> <p class="mb-0"> <b>Note:</b> Optimal tree shaking only works when your Nuxt.js app is in <code>production</code> mode. You may notice larger bundle sizes when not in <code>production</code> mode (i.e. <code>dev</code> mode). </p> </div>If you want to import individual BootstrapVue components into specific pages and/or components of
your Nuxt app, you may want to bypass the Nuxt.js module and, instead, follow the
module bundlers and
Tree shaking with module bundlers sections above.
Alternatively you may want to to just import a few plugins (such as LayoutPlugin) in your Nuxt.js
module config, and then import additional components or plugins in the pages where needed.
The icons plugin is not automatically installed when using the Nuxt.js module.
You must either explicitly enable the IconsPlugin, or specify which icon components you wish to
import.
All Icons:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
// Install the `IconsPlugin` plugin (in addition to `BootstrapVue` plugin)
icons: true
}
}
Specific icons:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
// Add the desired icon components to the `components` array
components: ['BIcon', 'BIconAlertFill', 'BIconCalendar', 'BIconGears']
}
}
Icons plugin:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
// Add the icon plugin to the `componentsPlugins` array
componentPlugins: ['IconsPlugin']
}
}
If you need to pass a custom
BootstrapVue configuration, you may
do so by setting the config property in your nuxt.config.js:
module.exports = {
modules: ['bootstrap-vue/nuxt'],
bootstrapVue: {
config: {
// Custom config options here
}
}
}
Nuxt.js module uses the pre-transpiled versions of BootstrapVue for faster development builds and
the source (src/) of BootstrapVue for higher quality and smaller production builds.
You can override this option using usePretranspiled option. Setting to true always uses the
pre-transpiled versions, while setting it to false will always use src/. By default
usePretranspiled is enabled in development mode only. You should not need to use this option as
the default is most optimal for performance.
Unlike V2, Vue CLI 3 doesn't use templates.
Create a new project in the directory my-project:
npx @vue/cli create my-project
Enter the my-project directory and install bootstrap-vue:
npm install bootstrap-vue
Under the hood, Vue CLI uses webpack, so we can register the BootstrapVue plugin as with the webpack instructions.
import Vue from 'vue'
import { BootstrapVue, BootstrapVueIcons } from 'bootstrap-vue'
import 'bootstrap/dist/css/bootstrap.css'
import 'bootstrap-vue/dist/bootstrap-vue.css'
Vue.use(BootstrapVue)
Vue.use(BootstrapVueIcons)
For additional configuration for Vue CLI 3 for using project relative paths for image src props on various BootstrapVue components, refer to the Vue CLI 3 section of the Image Src Resolving reference page.
As an alternative, you can use the Bootstrap-Vue Vue CLI 3 plugin to help you configure your app.
vue create my-app
cd my-app
vue add bootstrap-vue
This will create a new app with basic BootstrapVue settings to get your project started.
In the future this plugin will provide options for more advanced configurations and templates.
For Icons support, you may need to edit the resultant config file.
If not using a module bundler or compile process, you can instead add the Bootstrap and BootstrapVue
CSS URLs in your HTML <head> section, followed by the required JavaScript files.
When supporting older browsers (see Browser Support below), you will need to include a polyfill for handling modern JavaScript features before loading Vue and BootstrapVue JavaScript files.
<!-- Add this to <head> -->
<!-- Load required Bootstrap and BootstrapVue CSS -->
<link type="text/css" rel="stylesheet" href="https://unpkg.com/bootstrap@{{ bootstrapVersion }}/dist/css/bootstrap.min.css" />
<link type="text/css" rel="stylesheet" href="https://unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.css" />
<!-- Load polyfills to support older browsers -->
<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?version=4.8.0&features=es2015%2CIntersectionObserver" crossorigin="anonymous"></script>
<!-- Load Vue followed by BootstrapVue -->
<script src="https://unpkg.com/vue@{{ vueVersion }}/dist/vue.min.js"></script>
<script src="https://unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.js"></script>
<!-- Load the following for BootstrapVueIcons support -->
<script src="https://unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue-icons.min.js"></script>
Choosing the best variant for your build environment / packager helps reduce bundle sizes. If your bundler supports esm modules, it will automatically prefer it over commonjs.
| Variant | Environments | Tree Shake | Package path |
|---|---|---|---|
| ESM module | webpack 2+ / rollup.js | Yes | esm/index.js |
| ESM bundle | webpack 2+ / rollup.js | Yes | dist/bootstrap-vue.esm.js |
| commonjs2 | webpack 1 / ... | No | dist/bootstrap-vue.common.js or dist/bootstrap-vue.common.min.js |
| UMD | Browser | No | dist/bootstrap-vue.js or dist/bootstrap-vue.min.js |
Note the UMD (browser) variant does not include BootstrapVue icons support. All
other variants listed above do include the BootstrapVueIcons (IconsPlugin) plugin (note the
icons plugin is not automatically installed, and must explicitly installed via Vue.use(). See the
Icons usage section for more details.
Icons only modules:
| Variant | Environments | Tree Shake | Package path |
|---|---|---|---|
| ESM bundle | webpack 2+ / rollup.js | Yes | dist/bootstrap-vue-icons.esm.js |
| commonjs2 | webpack 1 / ... | No | dist/bootstrap-vue-icons.common.js or dist/bootstrap-vue-icons.common.min.js |
| UMD | Browser | No | dist/bootstrap-vue-icons.js or dist/bootstrap-vue-icons.min.js |
The ESM module build and the ESM bundles (single file) are
tree-shakeable, but you will experience smaller final bundle
sizes when using the ESM module vs. the ESM bundle.
All of the build variants listed above have been pre-transpiled targeting the
browsers supported by
BootstrapVue. However, if you are targeting only modern browsers, you may want to import
BootstrapVue from src/index.js, (by aliasing bootstrap-vue to bootstrap-vue/src/index.js)
and whitelisting bootstrap-vue/src for transpilation via your own project. This can potentially
reduce final project bundle sizes. See the
Using BootstrapVue source code for smaller bundles
section above for more details.
BootstrapVue relies on Popper.js (for Tooltip, Popover, and Dropdown positioning),
PortalVue (for toasts) and
vue-functional-data-merge (used by
our functional components). These three dependencies are included in the BootstrapVue UMD bundle,
while the UMD (browser) icons only bundle includes vue-functional-data-merge. All other builds do
not include these dependencies.
If you've already been using Bootstrap v{{bootstrapVersionMajor}}, there are a couple adjustments you may need to make to your project:
bootstrap.js file from your page scripts or build pipelinejQuery, you can safely remove it — BootstrapVue does
not depend on jQueryBootstrapVue is to be used with Bootstrap v{{bootstrapVersionMinor}} CSS/SCSS. Please see <b-link :href="bootstrapBrowserDevicesHref" target="_blank">Browsers and devices</b-link> for more information about browsers currently supported by Bootstrap v{{bootstrapVersionMajor}}.
BootstrapVue is written in Vue.js! So it is up to your project and bundler which browsers are supported.
Following features and APIs are used by BootstrapVue:
Array.from(), Array.isArray(), Object.assign(), Object.is(), etc.)PromiseMutationObserverIntersectionObserver (optional)If you want to support older IE, Android, and iOS device web browsers, you may want to use core-js and intersection-observer:
npm install core-js regenerator-runtime intersection-observer
Then import the polyfills in your app main entry point:
<!-- eslint-disable no-unused-vars -->import 'core-js/stable'
import 'regenerator-runtime/runtime'
import 'intersection-observer' // Optional
import Vue from 'vue'
import BootstrapVue from 'bootstrap-vue'
If using deprecated @babel/polyfill:
npm install @babel/polyfill intersection-observer
Then import the polyfills in your app main entry point:
<!-- eslint-disable no-unused-vars -->import '@babel/polyfill'
import 'intersection-observer' // Optional
import Vue from 'vue'
import BootstrapVue from 'bootstrap-vue'
Alternatively, use Cloudflare's polyfill to dynamically
serve browser specific polyfills via <script> tags in the HTML <head> section. See the
Browser section above for an example.
BootstrapVue provides additional helper files for auto completion in popular IDE editors.
If you are using VS Code as your text editor, BootstrapVue has
intellisense autocompletion for component attributes and directives available via the
dist/vetur-tags.json and dist/vetur-attributes.json files.
For WebStorm editor (or web-types compatible), BootstrapVue
provides the file dist/web-types.json for component attribute and directive auto-completion.