Migration Guide​

Overview​

BootstrapVueNext is an entirely new implementation ofBootstrapVue based onVue 3 andBootstrap 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 withVue 3,Bootstrap 5 and this library is a higher priority.

You should start by familiarizing yourself with theVue 3 Migration Guide, especially thebreaking changes section and theBootstrap 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 useBootstrap utility classes in order to style your components.Bootstrap 5 made abreaking change to all utility classes that involveleft andright (orl andr) to bestart andend (ors ande). This will affect components such asBNavBar in unexpected ways that BootstrapVueNext has no control over.

Similarly,left andright props and values in thebootstrap-vue-next API are generally replaced bystart andend.

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 withnuxt 3 so if you are usingnuxt, please read theirmigration guide and ourrouter link support reference

Status​

This migration guide is a work in progress. We're adding to this guide as we complete the documentation and parity pass and doing our best to note each component or directive that hasn't been through the full process.

If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

For section of this guide that are not marked as in progress, we're still interested in examples of migrations that you have found tricky or clarifcation if the details in the guide weren't sufficent.

Deprecation​

We will mark features of BootstrapVue as deprecated for one of several reasons.

• If there is a more streamlined or consistent way of providing the functionality in BootstrapVueNext
• If the feature is deprecated in Bootstrap 5
• If we believe that this functionality can as easily (or more easily) be consumed using native bootstrap classes
• If we haven't seen demand for the feature, especially if it is something we believe can be implemented later without a breaking change

For any deprecated feature, especially the last case listed above, please feel free to open anissue or submit a pull request.

Sync modifier​

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

For instance, in order to two-way bind to theindeterminate property inBFormCheckBox youv-bind to the model namedindeterminate rather than adding the sync modifier to theindeterminate 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 theVue 3 migration guide for more info.

Native Events​

BootstrapVue sometimes listed the native events such asclick that were bubbled from the underlying HTML element. We're not currently doing that, as we would like to keep the list of events consistent between the documentation and the code.

Shared Properties​

Rounding​

BAvatar,BAvatarGroup,BCardImg,BImg andBOverlay all implementRadiusElementExtendables in order to support complex rounding behavior. Therounded,rounded-top,rounded-bottom,rounded-start, androunded-end props each takes aRadiusElement value to specify how the component is rounded. The edge specific props such asrounded-top override therounded prop for that edge.

This takes the place oftop,bottom,left, andright values for therounded 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 thev-model rather thanvisible as inBCollapse,BModal,BToast. Note thatshow andvisible are still supported for specifying the initial visibility of these components.

Rather than usinghide as a prefix to specify that you don't want a sub-component to be rendered, we've moved to usingno as the prefix. For instant inBPlaceholder,hideHeader becomesnoHeader. Similarly we use the 'no' prefix in place of 'skip' in places likeBCollapse whereskipAnimation becomesnoAnimation.

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

v-html​

BootstrapVue provided a number of different props namedhtml and*-html that passed arbitrary data to Vue'sv-html. While a warning was included with each instance of this use, it is not recommended practice to usev-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 ofv-html will be explicit. See theVue Documentation for their take on theHTML Injection attack that use ofv-html exposes.

BootstrapVueb-popover didn't have anhtml attribute, but alpha versions of BootstrapVueNext did

BFormCheckboxGroup andBFormRadioGroup implement a scoped slotoption which takes aRecord<string, unknown> parameter. You can add arbitrary fields to elements of the options array that you pass in and they will be accessible to the slot. The example below uses the data on the options object to create the html inline in the slot.

<template>  <div>    <BFormCheckboxGroup      v-model="model"      :options="options"    >      <template #option="{value}">        {{ (valueas Name).first }} <b>{{ (valueas 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>

Or you can do a straightforward translation of aBFormRadioGroup passing anHTML string through to its children. If you're passing user data, this still opens your code uop toXSS attacks, if you do not firstsanitize the user supplied string, but the BootstrapVueNext library isn't adding an extra layer of abstraction to this vulnerability.

<!-- eslint-disable vue/no-v-html --><template>  <div>    <BFormGroup      class="form-group"      label="Color"      label-for="color-group"      label-class="mb-1"    >      <BFormRadioGroup        id="color-group"        v-model="model"        name="color-group"        button-variant="outline-secondary"        :options="options"        buttons      >        <template #option="val"> <div v-html="val.html" /> </template>      </BFormRadioGroup>    </BFormGroup>    <b>model = </b>{{ model }}  </div></template><script setup lang="ts">import {ref}from 'vue'const myColors = ['Black','Red','Green','Blue','Purple']const model = ref(myColors[0])const options = myColors.map((e)=> ({  value: e,  html:`<span style="color:${e.toLowerCase()}" /> ${e}`,}))</script>

Component aliases​

BootstrapVue had a number of component aliases — for instance,<b-btn> was an alias for<b-button>. BootstrapVueNext does not support these aliases by default, so you must use the canonical component names.

To define aliases, you can use theBootstrapVueNextResolver'saliases option.

The table below lists each BootstrapVue alias and its BootstrapVueNext replacement:

Note: While BootstrapVueNext recommends using Vue 3 naming conventionBButton it is still possible to useb-button.

Components​

Grid​

BootstrapVueNext doesn't currently implement the ability to definebreakpoint names.

See theBootstrap 5 migration guide, in particular values fororder on<BCol> only provides support for 1 - 5.

BAccordion​

SeeShow and Hide shared properties.

BAccordionItem​

SeeShow and Hide shared properties.

BAlert​

As inbootstrap-vue, a simpleBAlert is not visible by default. However, the means of showing the alert are different. Thebootstrap-vueshow prop is deprecated, usemodel-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 termdismissible inbootstrap-vue now use the termclose. For example thedismissed event is now theclosed event and thedismiss slot is now theclose slot.

BAspect​

BAvatar​

Icon support has been deprecated. Icons support can be implemented using the default slot including eitherunplug 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 propertybadge-placement and ourCombinedPlacement utility rather than individual properties.

For instance, usebadge-placement='top' in place ofbadge-top orbadge-placement='end' in place ofbadge-right. For combined props, rather than usingbadge-top andbadge-right, use `badge-placement='top-end'.

Rounding Sides​

See theRounding section.

BBadge​

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

BBreadcrumb​

See thev-html section for information on deprecation of thehtml prop.

BButton​

Theblock prop is deprecated. See ourBButton documentation andBootstrap's documentation for details.

BButtonClose​

BButtonClose has been renamed toBCloseButton for consistency withBootstrap

Thecontent andtext-variant props have been deprecated since Bootstrap 5 moved to using an embedded svg for the close icon. Seetheir migration guide for details.

BButtonToolbar​

Keyboard navigation is not implemented.

BCalendar​

BCard​

Image placement is accomplished by the singleimg-placement prop, which takes the valuestop,bottom,start,end, oroverlay. This allows us to deprecate theimgBottom,imgEnd,imgLeft,imgRight,imgStart, andimgTop props fromBCard.

Similarly, thetop,bottom,left, andright props onBCardImg are deprecated in favor of a singleplacement prop that take the valuestop,bottom,start, andend. Note thatend andstart are not yet implemented.

Thesub-title,sub-title-tag andsub-title-text-variant props have been renamed tosubtitle,subtitle-tag andsubtitle-text-variant, respectively.

ForBCardBody,BCardHeader,BCardFooter,BCardTitle, andBCardText components the component name specific props are deprecated and replaced by the generalized props. For examplefooter-bg-variant is replaced bybg-variant. This is true for all of thebody-*,header-*, andfooter-* props on these components. Note that the specific props are still retained on the mainBCard component.

Similarly thetext-tag andtitle-tag props have been replaced bytag on theBCardText andBCardTitle components.

body-border-variant andbody-variant are not implemented onBCard andborder-variant is not implemented onBCardBody.

See thev-html section for information on deprecation of thefooter-html andheader-html props onBCard and thehtml props onBCardFooter andBCardHeader.

BCardImgLazy​

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

BCarousel​

Thesliding-start andsliding-end events have been renamed toslide andslid. Thelabel-indicators prop has been renamed toindicators-button-label.

See thev-html section for information on deprecation of thecaption-html andtext-html props onBCarouselSlide.

BCollapse​

Theaccordion prop is deprecated: InBootstrapVue/Bootstrap4, accordions are implemented viaBCollapse. InBootstrapVueNext/Bootstrap5 accordions are first class citizens, so please use theBAccordion instead.

The proptoggle has replaced the propappear with slightly different semantics. In order to create a collapse that is closed and transitions to open on the initial mount, setvisible to false andtoggle to true.

Theclose scoped slot element has been replaced byhide for consistency with the other props and events on this component.

$root instance eventsbv::collapse::state andbv::toggle::collapse are deprecrated.

SeeShow and Hide shared properties.

BDropdown​

BootstrapVueNext usesfloating-ui to implemented dropdowns. This affects values and behaviors for properties such asboundary as well as the alignment and placement properties. For fine control, usefloating-middleware in place ofpopper-opts. Check outour documentation and [theirs] for details.

BootstrapVueNext replacesdrop-up,drop-left anddrop-right props with a singleplacement prop. Valid values forplacement are defined infloat-ui's docshere.

Theblock prop is deprecated. See ourBDropdown documentation andBootstrap's documentation for details.

Theright prop is replaced byend see theoverview section of this page for details.

Thehtml prop has been deprecated, use thebutton-content.

$root instance eventsbv::dropdown::hide andbv::dropdown::show are deprecated.

The boolean argument to control returning focus to the toggle button on thehide 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.

SeeShow and Hide shared properties.

See thev-html section for information on deprecation of thehtml prop.

Theclick event that was emitted when clicking on the left or button side of asplit dropdown has been replaced by asplit-click which provides the native mouse event. This is because naming the event 'click' was hiding the nativeclick event so supressing the that event for parents that might have unexpected actions (such as a link navigating to a new page) was difficult.

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 awrapper-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 adivider-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 explicitwrapper-attr tag defined to place additional attributes on the<li> tag.

Looking at the code forBDropdownDivider 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 explicitid prop, which sets the id on the inner component. In BootstrapVueNext theid 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 implementid in order to be able to generate a header id.

BDropdownForm​

inline is deprecated, see theBForm migration information. To add classes to the<form> tag inBdropdownForm use theform-class prop.

Thedisabled prop is deprecated, set the disabled prop on individual components as you do withBForm.

BEmbed​

BForm​

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

BForm Components​

Vue 3 changed the way thatv-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 thevalue property or thechange andinput events, you'll find that functionality in themodelValue property andupdate:model-value events. Bootstrap-vue-next no longer provides customchange andinput events, so the native versions of those events are now exposed.

See theVue 3 migration guide for more info.

See thev-html section for information on deprecation of thehtml prop onBFormDatalist,BFormRadioGroup,BFormSelect, andBFormSelectOptionGroup

BFormCheckbox​

SeeBForm Components

BFormDatePicker​

BFormFile​

This component is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

BFormGroup​

Uselabel-visually-hidden instead oflabel-sronly perBootstrap Migration Guide

BFormInput​

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

trim,lazy, ornumber properties have been deprecated. We support the native modifierstrim,lazy, andnumber. They work as documented in vue.js, so there is no longer a need for the properties.

BFormRadio​

SeeBForm Components

BFormRating​

BFormRating is now available in BootstrapVueNext, preserving most of the original BootstrapVue functionality under Vue 3's v-model conventions. See theVue 3 migration guide for details on the newv-model syntax.

The following features from BootstrapVue areNot yet implemented:

• disabled prop: Interactive disabling of the rating component
• Form submission: Thename prop for generating hidden inputs for form submission
• Input groups: UsingBFormRating withinBInputGroup components
• Internationalization: Thelocale prop for localized display and RTL support

Icon System Changes​

The following icon-related props from BootstrapVue have been deprecated:

• icon-empty: For specifying empty star icon
• icon-half: For specifying half-filled star icon
• icon-full: For specifying filled star icon
• icon-clear: For specifying clear button icon

Instead, BootstrapVueNext provides two approaches for customizing icons:

1. Default built-in SVG icons (recommended): Uses built-in star SVG icons that work withvariant,color, andsize props
2. Custom icons via scoped slots: For complete customization where you handle all styling yourself

Important: When using custom icons via scoped slots, thevariant,color, andsize props do not apply. You must handle all styling in your custom CSS.

BFormSelect​

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

BFormSpinButton​

SeeBForm Components

BFormTags​

In BootstrapVue, the event handlers for some of the other input controls, likeBFormSelect, lined up with theinputHandlers for the default slot's scoped properties such that one could directly bind them. See theBootstrapVue documentation for an example. This is no longer the case with BootstrapVueNext.

In general BootstrapVueNext prefered clean APIs to enabling this kind of matching of events, so many of the advanced examples in theBFormTags docs are more explicit when binding attributes from other controls. Please take a look at these examples for guidance when migrating.

BFormTimePicker​

BImg​

See theRounding section.

Lazy loading is now achieved through the nativeloading attribute rather than a separate component. ThusBImgLazy andBCardImgLazy are deprecated.

BImgLazy​

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

BInputGroup​

Bootstrap 5no longer requiresinput-group-append orinput-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 thev-html section for information on deprecation of theappend-html andprepend-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, pleasefile an issue with an explanation of the expected behavior.

BFormTextbox​

trim,lazy, ornumber properties have been deprecated. We support the native modifierstrim,lazy, andnumber. 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 theirmigration guide for details.

BLink​

Bootstrap Vue usedVue Router 3, BootstrapVueNext usesVue Router 4 please read theVue Router migration guide if using the router features ofBLink.

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

append​

Vue router deprecated theappend prop in<router-link>, BootstrapVueNext has followed suit and deprecated theappend prop onBLink. See theVue Router migration guide for details.

event​

Vue router deprecated theevent prop in<router-link>, BootstrapVueNext has followed suit and deprecated theevent prop onBLink. See theVue Router migration guide for details.

exact​

Vue router deprecated theexact prop in<router-link>, BootstrapVueNext has followed suit and deprecated theexact,exact-path andexact-path-active-class props onBLink. See theVue Router migration guide for details.

$root events​

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

BListGroup​

SeeBLink 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 theirdocumentation for details.

BModal​

footer-tag andheader-tag are deprecated, use thefooter andtitle slots instead. See themodal documentation for details.

Removed Global Modal Management​

$bvModal instance methods are deprecated:

• this.$bvModal.show(id) → UseuseModal composable or template refs with.show()
• this.$bvModal.hide(id) → UseuseModal composable or template refs with.hide()
• this.$bvModal.msgBoxOk() → UseuseModal().create() withok-only prop - seebelow
• this.$bvModal.msgBoxConfirm() → UseuseModal().create()- seebelow

$root event system is deprecated:

• $root.$emit('bv::show::modal', id) → Use composables or template refs
• $root.$emit('bv::hide::modal', id) → Use composables or template refs
• $root.$emit('bv::toggle::modal', id) → Use composables or template refs

Alternative approaches:

Please seeuseModal anduseToggle for alternative methods of accessing modals globally.

Modal Event System Changes​

The event system has been significantly updated in BootstrapVueNext:

There is no concept of listening to modal changes via$root events.

New Events: BootstrapVueNext adds several new events not present in BootstrapVue:

• backdrop - Emitted when the backdrop is clicked
• esc - Emitted when the Esc key is pressed
• show-prevented,hide-prevented,toggle-prevented - Emitted when actions are prevented

Event Object Changes: The event object structure has changed:

• BvModalEvent is nowBvTriggerableEvent
• vueTarget property isno longer available - use template refs or thetarget property instead
• Event properties are now more consistent across all BootstrapVueNext components

Trigger Values: Thetrigger property values have been simplified:

• BootstrapVue:'headerclose' → BootstrapVueNext:'close'
• All other trigger values remain the same:'ok','cancel','esc','backdrop'

Modal Props Changes​

Renamed props:

• hide-header-close →no-header-close
• hide-footer →no-footer
• hide-header →no-header
• hide-backdrop →no-backdrop
• no-enforce-focus →no-trap
• title-sr-only →title-visually-hidden

Removed props (not implemented in BootstrapVueNext):

• aria-label - Use standard HTML attributes directly on the component.Note: Unlike BootstrapVue, BootstrapVueNext does not automatically removearia-labelledby whenaria-label is present. If usingaria-label, setno-header="true" to prevent conflicts, or ensure youraria-label is descriptive enough to work alongsidearia-labelledby
• auto-focus-button - Use thefocus prop with values'ok','cancel', or'close'
• ignore-enforce-focus-selector - Useno-trap to disable focus trapping entirely
• return-focus - Focus return is handled automatically by the focus trap system
• static - All modals use teleport by default. Useteleport-disabled for local rendering

See thev-html section for information on deprecation of thecancel-title-html,ok-title-html, andtitle-html props.

New props in BootstrapVueNext:

• teleport-to - Specify where the modal should be teleported (default:'body')
• teleport-disabled - Render modal in place instead of teleporting
• body-scrolling - Allow body scrolling while modal is open
• backdrop-first - Control backdrop animation timing
• no-trap - Disable focus trapping (replacesno-enforce-focus)
• focus - Enhanced focus control replacingauto-focus-button
• title-visually-hidden - Hide title visually but keep for screen readers
• header-close-variant - Control close button variant
• header-close-label - Accessibility label for close button
• lazy -Available in BootstrapVueNext - When set, the content will not be mounted until opened
• no-fade -Available in BootstrapVueNext - Disables animation (alias forno-animation)
• no-animation - Disables animation
• unmount-lazy - When set andlazy is true, content will be unmounted when closed
• initial-animation - When set, enables the initial animation on mount

Changed behavior:

• header-close-content - This prop isremoved in BootstrapVueNext. In BootstrapVue, this prop allowed customizing the close button content (defaulted to'×'). In BootstrapVueNext, use theheader-close slot instead, which provides more flexibility than the simple string prop:

<!-- BootstrapVue --><BModal header-close-content="✕"> Modal content </BModal>

<!-- BootstrapVueNext --><BModal>  <template #header-close> ✕ </template>  Modal content</BModal>

Modal Slot changes​

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

Modal Slot Scoped Variables Changes​

The scoped variables available to modal slots have changed between BootstrapVue and BootstrapVueNext:

BootstrapVue slot scope:

const bootstrapVueSlotScope = {  ok: ()=> void 0,// Closes modal with trigger 'ok'  cancel: ()=> void 0,// Closes modal with trigger 'cancel'  close: ()=> void 0,// Closes modal with trigger 'headerclose'  hide: (trigger?: string)=> void 0,// Closes modal with custom trigger  visible:true,// Boolean visibility state}

BootstrapVueNext slot scope (BModalSlotsData):

interface BModalSlotsData extends ShowHideSlotsData {  cancel: ()=> void // Closes modal with trigger 'cancel'  close: ()=> void // Closes modal with trigger 'close' (note: 'close' not 'headerclose')  ok: ()=> void // Closes modal with trigger 'ok'}interface ShowHideSlotsData {  id: string // Modal ID string  show: ()=> void // Show the modal  hide: (trigger?: string,noTriggerEmit?: boolean)=> void // Enhanced hide method  toggle: ()=> void // Toggle modal visibility  active: boolean // Boolean - true when modal is active/visible  visible: boolean // Boolean - same as active, for compatibility}

Key changes:

• New properties:id,show(),toggle() are now available
• Enhancedhide() method: Now accepts optionalnoTriggerEmit parameter
• Trigger value change:close() now emits trigger'close' instead of'headerclose'
• Dual visibility properties: Bothactive andvisible provide the same visibility state

Modal Z-Index and Stacking Changes​

BootstrapVueNext has completely rewritten modal stacking:

• Automatic z-index management: No manual z-index calculation needed
• CSS variables for stacking: Uses--b-position,--b-inverse-position,--b-count
• Stack positioning classes: Automatically applies.stack-position-* classes
• Multiple modal support: Enhanced support for multiple modals with proper layering

Replacement for Modal Message boxes​

BootstrapVue provided two methods on thethis.$bvModal object calledmsgBoxOk andmsgBoxConfirm. In keeping with the Vue3 first philosophy, BootstrapVueNext provides a composable calleduseModal that fills the same use cases (and more).

Please read theuseModal documentation and then return here for examples of replacements formsgBoxOk andmsgBoxConfirm.

Example usinguseModal.create to replacemsgBoxOk: Note: If you use<BApp>, the modal orchestrator is included by default. If you’re not usingBApp, include<BOrchestrator /> at your app root.

<template>  <div>    <BButton @click="okBox">Show Message</BButton>    <div>Result: {{ okResult }}</div>  </div></template><script setup lang="ts">import {useModal}from 'bootstrap-vue-next/composables/useModal'import {ref}from 'vue'const {create}= useModal()const okResult = ref<boolean | null | undefined>(null)const okBox = async ()=> {  const value = await create({    body:'This is an informational message',    title:'Message',    okOnly:true,  }).show()  okResult.value= typeof value=== 'object' && value!== null && 'ok' in value? value.ok: null}</script>

Example usinguseModal.create to replacemsgBoxConfirm: Note: If you use<BApp>, the modal orchestrator is included by default. If you’re not usingBApp, include<BOrchestrator /> at your app root.

<template>  <div>    <BButton @click="confirmBox">Show Confirm</BButton>    <div>Result: {{ confirmResult?? 'null' }}</div>  </div></template><script setup lang="ts">import {useModal}from 'bootstrap-vue-next/composables/useModal'import {ref}from 'vue'const {create}= useModal()const confirmResult = ref<boolean | null | undefined>(null)const confirmBox = async ()=> {  const value = await create({    body:'Are you sure you want to do this?',    title:'Confirm',    okTitle:'Yes',    cancelTitle:'No',  }).show()  confirmResult.value=    typeof value=== 'object' && value!== null && 'ok' in value? value.ok: null}</script>

Thecreate method accepts all properties defined onBModal.

SeeShow and Hide shared properties.

Modal Focus Management Changes​

BootstrapVueNext uses a modern focus trap system with enhanced accessibility:

Enhanced focus prop: Thefocus prop replacesauto-focus-button and accepts:

• 'ok','cancel','close' - Focus built-in buttons
• Element references, selectors, or HTMLElements for custom focus targets
• false to disable initial focus (not recommended for accessibility)

Automatic focus return: Focus is automatically returned to the triggering element when the modal closes, eliminating the need for:

• return-focus prop - Handled automatically by focus trap
• Manual focus management in most cases

Focus trapping: Enabled by default using@vueuse/integrations/useFocusTrap:

• no-trap replacesno-enforce-focus to disable focus trapping
• ignore-enforce-focus-selector is not available - useno-trap if needed
• Focus automatically cycles within the modal

ARIA improvements:

• title-visually-hidden replacestitle-sr-only with better semantic naming
• Standard HTMLaria-* attributes work directly on the component
• Enhanced screen reader support with proper labeling

BNav​

align prop now takes values fromAlignmentJustifyContent:start,center,end,between,around, andevenly

BNavItemDropdown​

SeeBDropdown for details

See thev-html section for information on deprecation of thehtml prop.

BNavbar​

Thetype prop is deprecated. Use thev-b-color-mode directive oruseColorMode composable instead. Details in ourdocs

BNavbarNav​

align prop now takes values fromAlignmentJustifyContent:start,center,end,between,around, andevenly

BOffcanvas​

This component is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

SeeShow and Hide shared properties.

BOverlay​

See theRounding section.

propblur does not work when the propbgColor is defined. It also will not work if the propvariant is anything other thanwhite ortransparent. This overcomes a browser change.

BPagination​

SeeShow and Hide shared properties.

BPaginationNav​

BPopover​

SeeShow and Hide shared properties.

See thev-html section for information on deprecation of thehtml prop.

Thecontent prop has been renamed tobody for consistency with other components.

Thecontainer prop has been deprecated. Use theteleportTo prop instead to specify where the popover should be mounted. SeeVue Teleport documentation.

custom-class has been changed tobody-class and atitle-class has been added for completeness.

fallback-placement has been deprecated. Use the various options provided byfloating-ui to handle placement.

The ability for thetarget prop to take a function has been deprecated.

Triggers work differently as the underlying library we use to manage popovers has changed. Seeour documentation andfloating-ui for details.

Thevariant prop has been deprecated. Use Bootstrap's color and background utility classes to style popovers instead. SeePopover custom classes and variants for details.

Thedisabled prop andProgrammatically Disabling have been deprecated along with thedisabled andenabled events. Usemanual=true to disable BootstrapVueNext's automatic trigger handling and if your own code shows the popover disable those mechanisms as well. If you believe that implementing full parity with the BootstrapVue feature is useful, please open an issue or propose a pull request.

delay now defaults to 100ms for show and 300ms for hide rather than 50ms for both

The default forplacement is nowtop rather thanright

$root events are deprecated. SeeusePopover as an alternative.

BProgressBar​

See thev-html section for information on deprecation of thelabel-html prop.

BSkeleton​

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

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

<BSkeletonImg> is deprecated, using<BPlaceholderWrapper> should be a workable replacement.

animation values have changed fromWave,Fade,Throb andNone towave,glow, andundefined to reflect theBootstrap 5 animations

type has been deprecated.BPlaceholderButton is a replacement for the button type. If you find a need for the other types (Avatar or Input), please open an issue or propose a pull request.

BTable​

This component is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

See thev-html section for information on deprecation of thehtml prop.

The slotemptyfiltered has been renamed toempty-filtered for consistency.

The following areNot yet implemented -

• Thefilter-debounce,fixed,no-border-collapse,selected-variant, andtable-footer-sorting props
• Thefilter prop does not yet support a RegEx object, only a string.
• Thecontext-changed andrefreshed events

filter-included-fields have been replaced by a singlefilterable prop.filter-ignored-fields is deprecated.

no-sort-reset is deprecated. Usemust-sort. By default, sortability can be reset by clicking (3) times [asc => desc => undefined => asc...]

selected-variant has been renamed toselection-variant for internal consistency.

Sorting has been significantly reworked. Read thesorting section of our documentation. Some specific changes include the following:

• sort-changed event is replaced by theupdate:sort-by event.
• sort-direction has been renamedinitial-sort-direction for clarity.
• The sort icons have been changed.
• The internalsort-compare routine has been simplified, if you need to customize sorting for localization, the documentation oncustom sort comparers for details.
• multi-sort functionality has been implemented.

table-variant is replaced withvariant for consistency.

The slot scope fortable-colgroup slot now only contains thefields prop, with thecolumns prop removed.

BootstrapVue used the main v-model binding to expose a readonly version of the displayed items. This is deprecated. Instead, used the exposed functiondisplayedItems as demonstrated inthe documentation.

The semantics of therow-selected event have changed.row-selected is now emitted for each selected row and sends the single row's item as it's parameter. There is a new matching event calledrow-unselected that is emitted for each row that is unselected. There is also a named modelselectedItems that behaves like the BSVrow-selected event, emitting an array of all seleted rows. An example of this is available inthe documentation

BootstrapVue adds utility classes to the<table> includingb-table-select-single,b-table-select-multi, andb-table-select-range, these have been deprecated, as the functionality should be easily replicated by the developer without adding to the API surface.

Thefiltered event has a single argumentItems[] rather than two arguments with an array and length. The semantics haven't changed.

Items Provider Functions​

To use an items provider, set theprovider prop to a provider function and leave theitems prop undefined (unlike in BootstrapVue, where theitems prop was overloaded). See ourdocumentation for details.

The items provider functionctx parameter now containssortBy array rather thansortBy andsortDesc fields - see thesorting docs for details

The table propapi-url and the items provider functionctx parameterapiUrl field are both deperecdated as they are easily replaced by direct management of the api call by the user.

The items provider no longer includes an optional callback parameter, use the async method of calling instead.

Field Definitions​

formatter Only the callback function value for this field is implemented, adding the name of a method in the component is deprecated.

sortKey andsortDirection are deprecated, use the table'ssortBy model as documentedhere instead.

filterByFormatted is implemented, but does not take a format function as an argument.

BTableLight​

See thev-html section for information on deprecation of thehtml prop.

The slot scope fortable-colgroup slot now only contains thefields prop, with thecolumns prop removed.

BTableSimple​

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

See thev-html section for information on deprecation of thecaption-html prop.

BTBody​

BTFoot​

foot-variant has been replaced withvariant, which can used on other table elements.

BTHead​

head-variant has been replaced withvariant, which can used on other table elements.

BTabs​

align prop now takes values fromAlignmentJustifyContent:start,center,end,between,around, andevenly

The primaryv-model now reflects theid of the currently selected tag. Usev-model:index to syncronize to the current tab index. Seeprogrammatically activating and deactivating tabs for details.

Thechanged event onBTabs is deprecated.

BTime​

BToast​

Global Toast Management System Changes​

$bvToast instance methods are deprecated:

• this.$bvToast.show(options) → UseuseToast composable withcreate() method
• this.$bvToast.hide(target) → UseuseToast composable or template refs with.hide()
• this.$bvToast.hideAll() → UseuseToast composable

Named toaster system is deprecated:

• <b-toaster> targets → Use Vue'sTeleport component oruseToast positioning
• Toaster positioning CSS → Use CSS positioning on individual toasts or toast containers

Alternative approaches:

Please seeuseToast for the modern method of programmatically creating and managing toasts.

Props Changes​

Renamed props:

• visible →model-value - Controls both visibility and auto-dismiss timing (replaces separatevisible model)
• no-auto-hide → Setmodel-value tofalse ortrue (boolean) instead of using auto-hide duration
• auto-hide-delay → Setmodel-value to number of milliseconds for auto-dismiss duration

Removed props (not implemented in BootstrapVueNext):

• href andto - UseuseToast with BLink props or seeBLink Integration in the toast documentation
• toaster - UseTeleport oruseToast positioning instead
• append-toast - Available onBOrchestrator anduseToast instead
• b-toaster-* related props - Use modern positioning withTeleport
• static - BToast renders in place by default (no teleporting behavior)

New props in BootstrapVueNext:

• progress-props - Configure built-in progress bar for timed toasts
• no-progress - Hide progress bar on timed toasts
• show-on-pause - Control visibility when countdown is paused
• interval - Control countdown timer update frequency (default:'requestAnimationFrame')
• solid - Disable toast transparency (same as BootstrapVue)

Auto-dismiss Behavior Changes​

BootstrapVue: Used separate props for auto-hide configuration:

<BToast  auto-hide  auto-hide-delay="5000"  no-hover-pause/>

BootstrapVueNext: Usesmodel-value for both visibility and auto-dismiss:

<!-- Boolean for show/hide --><BToast v-model="show" /><!-- Number for auto-dismiss duration in milliseconds --><BToast  :model-value="5000"  no-hover-pause/>

Event System Changes​

Event naming changes:

• No$root event system - toasts are managed through composables or direct component references
• All events now use the standardized show/hide event lifecycle

New events: BootstrapVueNext adds several events:

• close-countdown - Emitted during countdown with remaining milliseconds
• update:model-value - Standard v-model event for visibility/duration changes
• Standard show/hide lifecycle events:show,shown,hide,hidden,show-prevented,hide-prevented,toggle,toggle-prevented

Slots Changes​

Renamed slots:

• toast-title →title - Toast header title content

Available slots:

• default - Toast body content (enhanced with slot scope data)
• title - Toast header title content (wastoast-title in BootstrapVue)
• close - Custom close button content (new in BootstrapVueNext)

Enhanced slot scope: All slots now receive scope data with control functions:

• id - Toast component ID
• show() - Function to show the toast
• hide() - Function to hide the toast
• toggle() - Function to toggle visibility
• visible - Current visibility state
• active - Whether countdown timer is active

Accessibility Improvements​

Enhanced ARIA support:

• isStatus prop correctly toggles betweenrole="alert" (default) androle="status"
• Correspondingaria-live values:"assertive" (default) and"polite"
• aria-atomic="true" automatically applied for better screen reader announcements
• tabindex="0" for keyboard accessibility

SeeShow and Hide shared properties.

BToaster​

TheBToaster component has been deprecated. Its functionality has been replaced by theuseToast composable working in concert with theBOrchestrator component. See the documentation for details.

BTooltip​

SeeShow and Hide shared properties.

See thev-html section for information on deprecation of thehtml prop.

BTooltip is noninteractive by default, unlike in BootstrapVue. This provides for a smoother user experience. Theinteractive prop is provided to restore the BootstrapVue behavior.

Thecontainer prop has been deprecated. Use theteleportTo prop instead to specify where the tooltip should be mounted. SeeVue Teleport documentation.

custom-class has been changed tobody-class and atitle-class has been added for completeness - seecustom classes documentation for details.

fallback-placement has been deprecated. Use the various options provided byFloating UI to handle placement.

The ability for thetarget prop to take a function has been deprecated.

Trigger behavior differs because the underlying library used to manage tooltips and popovers has changed. Seeour documentation andFloating UI for details.

Thevariant prop has been deprecated. Use Bootstrap’s color and background utility classes to style tooltips instead. SeeTooltip custom classes and variants for details.

Thedisabled prop andProgrammatically Disabling have been deprecated along with thedisabled andenabled events. Usemanual=true to disable BootstrapVueNext’s automatic trigger handling. If your application shows the tooltip programmatically, disable those automatic triggers as well. If you believe full parity with the BootstrapVue feature is useful, please open an issue or propose a pull request.

delay now defaults to 0 rather than 50ms

The default forplacement is nowtop rather thanright

$root events are deprecated. SeeusePopover as an alternative.

Directives​

Hover​

Modal​

This directive is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

Popover​

This directive is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

ScrollSpy​

This directive is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

Toggle​

This directive is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

Tooltip​

This directive is either not documented or has not been through full parity review. Please use with caution and refer to the code to find differences in behavior. We are working to bring the migration guide and documenation up-to-date with the code. If you would like to help, please refer to the improving the documentation andhelp verify parity sections of ourcontribution guide.

Visible​