Migration Guide ​

Overview ​

BootstrapVueNext is an entirely new implementation of BootstrapVue based on Vue 3 and Bootstrap 5. Therefore, you should not expect this to be a drop-in replacement. Where possible compatibility has been maintained, but providing a clean developer experience when working with Vue 3, Bootstrap 5 and this library is a higher priority.

You should start by familiarizing yourself with the Vue 3 Migration Guide, especially the breaking changes section and the Bootstrap 5 migration guide. While there are some places where this library will insulate you from the changes to the underlying libraries, a general familiarity with the changes in the core dependencies will serve you well.

For instance, there are likely many places where you use Bootstrap utility classes in order to style your components. Bootstrap 5 made a breaking change to all utility classes that involve left and right (or l and r) to be start and end (or s and e). This will affect components such as BNavBar in unexpected ways that BootstrapVueNext has no control over.

Similarly, left and right props and values in the bootstrap-vue-next API are generally replaced by start and end.

Bootstrap-vue-next will commit to breaking changes whenever Bootstrap marks something as "deprecated". These changes may be resolved automatically, or they might necessitate manual action from the library's users.

Nuxt ​

bootstrap-vue-next integrates with nuxt 3 so if you are using nuxt, please read their migration guide and our router link support reference

Sync modifier ​

A number of components in bootstrap-vue use v-bind's .sync modifier. This modifier has been replaced by properties on the the model (generally named models).

For instance, in order to two-way bind to the indeterminate property in BFormCheckBox you v-bind to the the model named indeterminate rather than adding the sync modifier to the indeterminate property:

<BFormCheckbox v-model="checked" :indeterminate.sync="indeterminate"
  >Click me to see what happens</BFormCheckbox
>

becomes

<BFormCheckbox v-model="checked" v-model:indeterminate="indeterminate">
  Click me to see what happens
</BFormCheckbox>

See the Vue 3 migration guide for more info.

Shared Properties ​

Rounding ​

BAvatar, BAvatarGroup, BCardImg, BImg and BOverlay all implement RadiusElementExtendables in order to support complex rounding behavior. The rounded, rounded-top, rounded-bottom, rounded-start, and rounded-end props each takes a RadiusElement value to specify how the component is rounded. The edge specific props such asrounded-top override the rounded prop for that edge.

This takes the place of top, bottom, left, and right values for the rounded prop.

Show and Hide ​

We have made an effort to standardize the names and behaviors of props that are related to the showing and hiding of components and sub-components.

The primary reactive way to control the visibility of a component is generally by use of the v-model rather than a visible as in BCollapse, BModal, BToast.

Rather than using hide as a prefix to specify that you don't want a sub-component to be rendered, we've moved to using no as the prefix. For instant in BPlaceholder, hideHeader becomes noHeader. Similarly we use the 'no' prefix in place of 'skip' in places like BCollapse where skipAnimation becomes noAnimation.

The properties and components that are affected by this change are show in the following table:

v-html ​

BootstrapVue provided a number of different props named html and *-html that passed arbitrary data to Vue's v-html. While a warning was included with each instance of this use, it is not recommended practice to use v-html and obscuring that practice further by passing down other props is ill advised in our opinion. We have instead worked to insure that you have the ability to access the same functionality via slots. In many cases slots were already available and took priority over the [*-]html props and we've filled in the gaps where there wasn't a direct replacement. We believe the developer experience in these cases is as good or better than when using props. Most importantly any use your code makes of v-html will be explicit. See the Vue Documentation for their take on the HTML Injection attack that use of v-html exposes.

BootstrapVue b-popover didn't have an html attribute, but alpha versions of BootstrapVueNext did

Each of the options group components BFormDatalist, BFormRadioGroup, BFormSelect, and BFormSelectOptionGroup implements a scoped slot option which takes a SelectOption<T> parameter.

<template>
  <div>
    <BFormCheckboxGroup v-model="model" :options="options">
      <template #option="{value}">
        {{ (value as Name).first }} <b>{{ (value as Name).last }}</b>
      </template>
    </BFormCheckboxGroup>
    <b>model = </b>{{ model }}
  </div>
</template>

<script setup lang="ts">
import type {CheckboxOption} from 'bootstrap-vue-next'
import {ref} from 'vue'

interface Name {
  first: string
  last: string
}

const model = ref<CheckboxOption[]>([])
const options = [
  {value: {last: 'Brown', first: 'Christina'}},
  {value: {last: 'Smith', first: 'John'}},
  {value: {last: 'Doe', first: 'Jane'}},
  {value: {last: 'Johnson', first: 'Michael'}},
  {value: {last: 'Williams', first: 'Patricia'}},
  {value: {last: 'Jones', first: 'Robert'}},
  {value: {last: 'Garcia', first: 'Linda'}},
]
</script>

Components ​

Grid ​

BootstrapVueNext doesn't currently implement the ability to define breakpoint names.

See the Bootstrap 5 migration guide, in particular values for order on <BCol> only provides support for 1 - 5.

BAccordion ​

See Show and Hide shared properties.

BAccordionItem ​

See Show and Hide shared properties.

BAlert ​

As in bootstrap-vue, a simple BAlert is not visible by default. However, the means of showing the alert are different. The bootstrap-vue show prop is deprecated, use model-value instead.

<BAlert variant="primary" show>A simple primary alert—check it out!</BAlert>

becomes

<BAlert :model-value="true" variant="primary">A simple primary alert—check it out!</BAlert>

For consistency with other components properties, slots and events that use the term dismissible in bootstrap-vue now use the term close. For example the dismissed event is now the closed event and the dismiss slot is now the close slot.

BAspect ​

BAvatar ​

Icon support has been deprecated. Icons support can be implemented using the default slot including either unplug icons or by embedding an .svg.

<BAvatar>
  <svg
    xmlns="http://www.w3.org/2000/svg"
    width="80%"
    height="80%"
    fill="currentColor"
    class="bi bi-person-hearts"
    viewBox="0 0 16 16"
  >
    <path
      fill-rule="evenodd"
      d="M11.5 1.246c.832-.855 2.913.642 0 2.566-2.913-1.924-.832-3.421 0-2.566M9 5a3 3 0 1 1-6 0 3 3 0 0 1 6 0m-9 8c0 1 1 1 1 1h10s1 0 1-1-1-4-6-4-6 3-6 4m13.5-8.09c1.387-1.425 4.855 1.07 0 4.277-4.854-3.207-1.387-5.702 0-4.276ZM15 2.165c.555-.57 1.942.428 0 1.711-1.942-1.283-.555-2.281 0-1.71Z"
    />
  </svg>
</BAvatar>

Badge Positioning ​

Badge positioning has changed to using a single property badge-placement and our CombinedPlacement utility rather than individual properties.

For instance, use badge-placement='top' in place of badge-top or badge-placement='end' in place of badge-right. For combined props, rather than using badge-top and badge-right, use `badge-placement='top-end'.

Rounding Sides ​

See the Rounding section.

BBadge ​

Badges no longer have focus or hover styles for links. See the Bootstrap migration guide for more information.

BBreadcrumb ​

See the v-html section for information on deprecation of the html prop.

BButton ​

The block prop is deprecated. See our BButton documentation and Bootstrap's documentation for details.

BButtonClose ​

BButtonClose has been renamed to BCloseButton for consistency with Bootstrap

The content and text-variant props have been deprecated since Bootstrap 5 moved to using an embedded svg for the close icon. See their migration guide for details.

BButtonToolbar ​

Keyboard navigation is not implemented.

BCalendar ​

BCard ​

Image placement is accomplished by the single img-placement prop, which takes the values top, bottom, start, end, or overlay. This allows us to deprecate the imgBottom, imgEnd, imgLeft, imgRight, imgStart, and imgTop props from BCard.

Similarly, the top, bottom, left, and right props on BCardImg are deprecated in favor of a single placement prop that take the values top, bottom, start, and end. Note that end and start are not yet implemented.

The sub-title, sub-title-tag and sub-title-text-variant props have been renamed to subtitle, subtitle-tag and subtitle-text-variant, respectively.

For BCardBody, BCardHeader, BCardFooter, BCardTitle, and BCardText components the component name specific props are deprecated and replaced by the generalized props. For example footer-bg-variant is replaced by bg-variant. This is true for all of the body-*, header-*, and footer-* props on these components. Note that the specific props are still retained on the main BCard component.

Similarly the text-tag and title-tag props have been replaced by tag on the BCardText and BCardTitle components.

body-border-variant and body-variant are not implemented on BCard and border-variant is not implemented on BCardBody.

See the v-html section for information on deprecation of the footer-html and header-html props on BCard and the html props on BCardFooter and BCardHeader.

BCardImgLazy ​

This functionality has been replaced by lazy loading on <BImg> see BImg notes for details.

BCarousel ​

The sliding-start and sliding-end events have been renamed to slide and slid. The label-indicators prop has been renamed to indicators-button-label.

See the v-html section for information on deprecation of the caption-html and text-html props on BCarouselSlide.

BCollapse ​

The accordion prop is deprecated: In BootstrapVue/Bootstrap4, accordions are implemented via BCollapse. In BootstrapVueNext/Bootstrap5 accordions are first class citizens, so please use the BAccordion instead.

The prop toggle has replaced the prop appear with slightly different semantics. In order to create a collapse that is closed and transitions to open on the initial mount, set visible to false and toggle to true.

The close scoped slot element has been replaced by hide for consistency with the other props and events on this component.

$root instance events bv::collapse::state and bv::toggle::collapse are deprecrated.

See Show and Hide shared properties.

BDropdown ​

BootstrapVueNext uses floating-ui to implemented dropdowns. This affects values and behaviors for properties such as boundary as well as the alignment and placement properties. For fine control, use floating-middleware in place of popper-opts. Check out our documentation and [theirs] for details.

BootstrapVueNext replaces drop-up, drop-left and drop-right props with a single placement prop. Valid values for placement are defined in float-ui's docs here.

The block prop is deprecated. See our BDropdown documentation and Bootstrap's documentation for details.

The right prop is replaced by end see the overview section of this page for details.

The html prop has been deprecated, use the button-content.

$root instance events bv::dropdown::hide and bv::dropdown::show are deprecated.

The the boolean argument to control returning focus to the toggle button on the hide scoped property of the default slot is deprecated. It is less important in BootstrapVueNext since bootstrap v5 by default doesn't have the focus ring that v4 has.

See Show and Hide shared properties.

See the v-html section for information on deprecation of the html prop.

Dropdown sub-components ​

BootstrapVueNext makes extensive use of inherited attributes to implement customization in dropdown sub-components in places where BootstrapVue used explicit props on the sub-components. In general the sub-components are implemented as an <li> element wrapping the actual sub-component. In these cases, there is a wrapper-class prop that is used to apply classes to the <li> element and an *-class prop that is used to apply classes to the sub-component where *-class is related the name of the sub-component. e.g. BDropdownDivider has a divider-class prop that is used to add classes to the actual divider element. In addition, the inherited attributes are applied to the sub-component rather than the wrapper <li> tag and there is an explicit wrapper-attr tag defined to place additional attributes on the <li> tag.

Looking at the code for BDropdownDivider should give a clear picture how how the above fits together and the remainder of this section will give specifics on how to handle migration from BootstrapVue.

Several of the BootstrapVue sub-components have an explicit id prop, which sets the id on the inner component. In BootstrapVueNext the id as well as any other unspecified props will be set will be set on the inner component, having the same effect as in BootstrapVue.

For example:

<BDropdownHeader id="header-label"> A nice description </BDropdownHeader>

yields

<li role="presentation">
  <h6 class="dropdown-header" id="header-label">A nice description</h6>
</li>

The exception to this rule is <BDropdownGroup> where we explicitly implement id in order to be able to generate a header id.

BDropdownForm ​

inline is deprecated, see the BForm migration information. To add classes to the <form> tag in BdropdownForm use the form-class prop.

The disabled prop is deprecated, set the disabled prop on individual components as you do with BForm.

BEmbed ​

BForm ​

Bootstrap 5 has dropped form-specific layout classes for the grid system. See the Bootstrap 5 Changelog, so we no longer explicitly implement and inline property on the BForm component nor is there a BFormRow component. Inline forms are still supported through use of bootstrap classes. See the inline form documentation for more info.

BForm Components ​

Vue 3 changed the the way that v-model binding works and in the process changed the guidance when naming the main model property and events for the primary model. bootstrap-vue-next follows this guidance, which affects all of the wrappers for form input. If you're looking for the value property or the change and input events, you'll find that functionality in the modelValue property and update:model-value events. Bootstrap-vue-next no longer provides custom change and input events, so the native versions of those events are now exposed.

See the Vue 3 migration guide for more info.

See the v-html section for information on deprecation of the html prop on BFormDatalist, BFormRadioGroup, BFormSelect, andBFormSelectOptionGroup

BFormCheckbox ​

See BForm Components

BFormDatePicker ​

BFormFile ​

BFormGroup ​

Use label-visually-hidden instead of label-sronly per Bootstrap Migration Guide

BFormInput ​

Access to the native input element is implemented differently due to changes in how Vue 3 handles references. See the BFormInput documentation for more details.

trim, lazy, or number properties have been deprecated. We support the native modifiers trim, lazy, and number. They work as documented in vue.js, so there is no longer a need for the properties.

BFormRadio ​

See BForm Components

BFormRating ​

BFormSelect ​

Options as an object was deprecated in BootstrapVue and never implemented in BootstrapVueNext

BFormSpinButton ​

See BForm Components

BFormTimePicker ​

BImg ​

See the Rounding section.

Lazy loading is now achieved through the native loading attribute rather than a separate component. Thus BImgLazy and BCardImgLazy are deprecated.

BImgLazy ​

This functionality has been replaced by lazy loading on <BImg> see BImg for details.

BInputGroup ​

Bootstrap 5 no longer requires input-group-append or input-group-prepend on elements to append or prepend them to the control, they can just be added as direct children of the input group. Due to this change <BInputGroupAppend>, <BInputGroupPrepend>, and <BInputGroupAddon> are no longer necessary and have been deprecated. This also has implications on the use of <BInputGroupText> - in BootstrapVue, this component was used form grouping sub-components. In BootstrapVueNext, <BInputGroupText> should only be used to apply styles to textual elements appended or prepended to a group. Using it to group components breaks the automatic append and prepend stylings.

See the v-html section for information on deprecation of the append-html and prepend-html props.

BInputGroupAddon ​

Deprecated - See [BInputGroup]

BInputGroupAppend ​

Deprecated - See [BInputGroup]

BInputGroupText ​

Deprecated - See [BInputGroup]

BInputGroupPrepend ​

Deprecated - See [BInputGroup]

BFormSpinbutton ​

The locale property in BootstrapVueNext only allows a for a single locale, while BSV allows for an array of locales. If this is a limitation that affect your scenario, please file an issue with an explanation of the expected behavior.

BFormTextbox ​

trim, lazy, or number properties have been deprecated. We support the native modifiers trim, lazy, and number. They work as documented in vue.js, so there is no longer a need for the properties.

BJumbotron ​

Note that Bootstrap has deprecated their Jumbotron component, but it can be replicated using utility classes. See their migration guide for details.

BLink ​

Bootstrap Vue used Vue Router 3, BootstrapVueNext uses Vue Router 4 please read the Vue Router migration guide if using the router features of BLink.

BLink no longer supresses the scroll to top default behavior when href='#'.

append ​

Vue router deprecated the append prop in <router-link>, BootstrapVueNext has followed suit and deprecated the append prop on BLink. See the Vue Router migration guide for details.

event ​

Vue router deprecated the event prop in <router-link>, BootstrapVueNext has followed suit and deprecated the event prop on BLink. See the Vue Router migration guide for details.

exact ​

Vue router deprecated the exact prop in <router-link>, BootstrapVueNext has followed suit and deprecated the exact, exact-path and exact-path-active-class props on BLink. See the Vue Router migration guide for details.

$root events ​

BootstrapVueNext no longer emits the bv::link::clicked event on $root.

BListGroup ​

See BLink for changes to link and router behavior.

BMedia ​

Note that Bootstrap has deprecated their Media object, but it can be replicated using flex utility classes. See their documentation for details.

BModal ​

See the v-html section for information on deprecation of the cancel-title-html, ok-title-html, and title-html props.

Replacement for Modal Message boxes ​

BootstrapVue provided two methods on the this.$bvModal object called msgBoxOk and msgBoxConfirm. In holding with the Vue3 first philosophy, BootstrapVueNext provides a composable called useModalController that fills the same needs (and more).

Please read the useModalController documentation and then come back here for examples of replacements for msgBoxOk and msgBoxConfirm.

Example using useModalController.show to replace msgBoxOk (Remember to include <BModalOrchestrator /> in your App Root):

<template>
  <div>
    <BButton @click="okBox">Show Message</BButton>
    <div>Result: {{ okResult }}</div>
  </div>
</template>

<script setup lang="ts">
import {useModalController} from 'bootstrap-vue-next'
import {ref} from 'vue'

const {show} = useModalController()

const okResult = ref<boolean | null | undefined>(undefined)

const okBox = async () => {
  okResult.value = await show?.({
    props: {
      body: 'This is an informational message',
      title: 'Message',
      okOnly: true,
    },
  })
}
</script>

Example using useModalController.confirm to replace msgBoxConfirm (Remember to include <BModalOrchestrator /> in your App Root):

<template>
  <div>
    <BButton @click="confirmBox">Show Confirm</BButton>
    <div>Result: {{ confirmResult ?? 'null' }}</div>
  </div>
</template>

<script setup lang="ts">
import {useModalController} from 'bootstrap-vue-next'
import {ref} from 'vue'

const {confirm} = useModalController()
const confirmResult = ref<boolean | null | undefined>(null)

const confirmBox = async () => {
  confirmResult.value = await confirm?.({
    props: {
      body: 'Are you sure you want to do this?',
      title: 'Confirm',
      okTitle: 'Yes',
      cancelTitle: 'No',
    },
  })
}
</script>

The show and confirm props object accepts all of the properties that are defined on BModal except for modelValue.

See Show and Hide shared properties.

Replacement for Modal slots ​

BootstrapVue provides different slots to configure some pieces of the modal component. These slots are slightly different in BootstrapVueNext:

BNav ​

align prop now takes values from AlignmentJustifyContent: start, center, end, between, around, and evenly

BNavItemDropdown ​

See BDropdown for details

See the v-html section for information on deprecation of the html prop.

BNavbar ​

The type prop is deprecated. Use the the v-b-color-mode directive or useColorMode composable instead. Details in our docs

BNavbarNav ​

align prop now takes values from AlignmentJustifyContent: start, center, end, between, around, and evenly

BOffcanvas ​

See Show and Hide shared properties.

BPagination ​

See Show and Hide shared properties.

BPaginationNav ​

BPopover ​

See Show and Hide shared properties.

See the v-html section for information on deprecation of the html prop.

BProgressBar ​

See the v-html section for information on deprecation of the label-html prop.

BSkeleton ​

<BSkeleton*> components have been replaced by the more appropriately named <BPlaceholder*> components.

<BSkeletonIcon> is deprecated along with the rest of the the BootstrapVue icon support. See our icon documentation for details. This functionality can be replicated by using <BPlaceholderWrapper> with your choice of icon replacement in the loading slot.

BTable ​

See the v-html section for information on deprecation of the html prop.

BTableLight ​

See the v-html section for information on deprecation of the html prop.

BTableSimple ​

Use table-attrs to apply additional attributes to the <table> element in reponsive mode.

See the v-html section for information on deprecation of the caption-html prop.

BTHead ​

head-variant has been replaced with variant, which can used no other table elements.

BTabs ​

align prop now takes values from AlignmentJustifyContent: start, center, end, between, around, and evenly

• click event is not implemented on BTab
• changed event is not implemented on BTabs

BTime ​

BToast ​

See Show and Hide shared properties.

BTooltip ​

See Show and Hide shared properties.

Directives ​

Hover ​

Modal ​

Popover ​

ScrollSpy ​

Toggle ​

Tooltip ​

Visible ​