Modal

Modals are streamlined, but flexible dialog prompts powered by JavaScript and CSS. They support a number of use cases from user notification to completely custom content and feature a handful of helpful sub-components, sizes, variants, accessibility, and more.

Usage

HTML
vue
<template>
  <BButton @click="modal = !modal"> Toggle modal </BButton>
  <BModal v-model="modal" title="Hello, World!"> Foobar? </BModal>
</template>

<script setup lang="ts">
const modal = ref(false)
</script>

Changing state via root

At this time, there is no built in functionality for toggling a modal in a global state. A simple workaround to be able to modify the state of the modal is to use a global state management tool like pinia. By simply v-modelling to a ref managed by the pinia state you can open and close the modal without context. This is not a perfect solution and will be looked at further in the future. Alternatively, you can export a ref from an external file and v-model to that.

Prevent Closing

It is possible to prevent showing/closing modals. You can prevent hiding on the following Events: ok, cancel, close, and hide.

HTML
vue
<template>
  <BButton @click="preventableModal = !preventableModal"> Toggle modal </BButton>

  <BModal v-model="preventableModal" title="Hello, World!" @hide="preventFn">
    Foobar?
    <BFormCheckbox v-model="preventModal">Prevent close</BFormCheckbox>
  </BModal>
</template>

<script setup lang="ts">
const preventableModal = ref(false)
const preventModal = ref(true)
const preventFn = (e: Event) => {
  if (preventModal.value) e.preventDefault()
}
</script>

Scrolling long content

When modals become too long for the user's viewport or device, they scroll independent of the page itself. Try the demo below to see what we mean.

HTML
vue
<template>
  <BButton v-b-modal.modal-tall>Launch overflowing modal</BButton>

  <BModal id="modal-tall" title="Overflowing Content">
    <p class="my-4" v-for="i in 20" :key="i">
      Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in,
      egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
    </p>
  </BModal>
</template>

You can also create a scrollable modal that allows the scrolling of the modal body by setting the prop scrollable to true.

HTML
vue
<template>
  <BButton v-b-modal.modal-scrollable>Launch scrolling modal</BButton>

  <BModal id="modal-scrollable" scrollable title="Scrollable Content">
    <p class="my-4" v-for="i in 20" :key="i">
      Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in,
      egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
    </p>
  </BModal>
</template>

Vertically centered modal

Vertically center your modal in the viewport by setting the centered prop.

HTML
vue
<template>
  <BButton v-b-modal.modal-center>Launch centered modal</BButton>

  <BModal id="modal-center" centered title="BootstrapVue">
    <p class="my-4">Vertically centered modal!</p>
  </BModal>
</template>

Feel free to mix vertically centered with scrollable.

Multiple Modal Support

HTML
vue
<template>
  <BButton @click="nestedModal1 = !nestedModal1">Open First Modal</BButton>

  <BModal v-model="nestedModal1" size="lg" title="First Modal" ok-only no-stacking>
    <p class="my-2">First Modal</p>
    <BButton @click="nestedModal2 = !nestedModal2">Open Second Modal</BButton>
  </BModal>

  <BModal v-model="nestedModal2" title="Second Modal" ok-only>
    <p class="my-2">Second Modal</p>
    <BButton @click="nestedModal3 = !nestedModal3" size="sm">Open Third Modal</BButton>
  </BModal>

  <BModal v-model="nestedModal3" size="sm" title="Third Modal" ok-only>
    <p class="my-1">Third Modal</p>
    <BButton @click="nestedModal4 = !nestedModal4" size="sm">Open Fouth Modal</BButton>
  </BModal>
  <BModal v-model="nestedModal4" size="sm" title="Fourth Modal" ok-only>
    <p class="my-1">Fourth Modal</p>
  </BModal>
</template>

<script setup lang="ts">
const nestedModal1 = ref(false)
const nestedModal2 = ref(false)
const nestedModal3 = ref(false)
const nestedModal4 = ref(false)
</script>
<style>
/* just a little example of the variables and classes for stack */
.modal {
  --bs-modal-zindex: 1900;
  transform: translate(
    calc((var(--b-count, 0) - var(--b-position, 0)) * 20px),
    calc((var(--b-count, 0) - var(--b-position, 0)) * 20px)
  );
  transition:
    transform 0.5s,
    opacity 0.15s linear !important;
}
.modal:not(.stack-inverse-position-0) {
  opacity: calc(1 - ((var(--b-count, 0) - var(--b-position, 0)) * 0.1));
}
.modal-backdrop:not(.stack-inverse-position-0) {
  opacity: 0 !important;
}
</style>

Programmatically Control

To programmatically control your modals with global state, refer to our documentation at useModal and useModalController

Programmatically Create Modals

To programmatically create modals, refer to the documentation at useModalController

If you're looking for replacements for $bvModal.msgBoxOk and $bvModal.msgBoxConfirm please see the migration guide

Component Reference

PropTypeDefaultDescription
backdrop-firstbooleanfalse Animates the backdrop before the modal and, on leave, animates the modal before the backdrop
bodystringundefined
body-attrsReadonly<AttrsValue>undefined
body-bg-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the body background
body-classClassValuenull CSS class (or classes) to apply to the '.modal-body' wrapper element
body-scrollingbooleanfalse Enables or disables scrolling the body while the modal is open
body-text-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the body text
body-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the body (takes priority over bodyBgVariant and bodyTextVariant)
busybooleanfalse Places the built-in default footer OK and Cancel buttons in a disabled state
button-sizeSize'md'
cancel-classClassValueundefined CSS class (or classes) to apply to the '.modal-cancel' button
cancel-disabledbooleanfalse Places the built-in default footer Cancel button in a disabled state
cancel-titlestring'Cancel' Text to place in the default footer Cancel button
cancel-variantButtonVariant | null'secondary' Variant for the default footer Cancel button
centeredbooleanfalse Vertically centers the modal in the viewport
content-classClassValueundefined CSS class (or classes) to apply to the '.modal-content' wrapper element
dialog-classClassValueundefined CSS class (or classes) to apply to the '.modal-dialog' wrapper element
focus'ok' | 'cancel' | 'close' | string | ComponentPublicInstance | HTMLElement | nullundefined Specify where to focus once modal opens. Can be built-in button: 'ok', 'cancel', or 'close'. Can be ref, HTMLElement, ID, or selector string. If set to 'false', no focus will be set (if noTrap isn't set, the focus trap will focus the modal element or fallback element). If set to a string, the element with that ID will be focused. If set to a ComponentPublicInstance, the $el property of the instance will be focused.
footer-bg-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the footer background
footer-border-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the footer border
footer-classClassValueundefined CSS class (or classes) to apply to the '.modal-footer' wrapper element
footer-text-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the footer text
footer-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the footer (takes priority over footerBgVariant and footerTextVariant)
fullscreenboolean | Breakpointfalse Enables full-screen mode with a boolean value or sets the breakpoint for full-screen mode below the specified breakpoint value ('sm', 'md', 'lg', 'xl', 'xxl')
header-bg-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the header background
header-border-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the header border
header-classClassValueundefined CSS class (or classes) to apply to the '.modal-header' wrapper element
header-close-classClassValueundefined CSS class (or classes) to apply to the header close button
header-close-labelstring'Close' Accessibility label for the header close button
header-close-variantButtonVariant | null'secondary' Variant for the header close button when using the header-close slot
header-text-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the header text
header-variantColorVariant | nullnull Applies one of the Bootstrap theme color variants to the header (takes priority over headerBgVariant and headerTextVariant)
idstringundefined Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
initial-animationbooleanfalse When set, enables the initial animation on mount
lazybooleanfalse When set, the content will not be mounted until opened
modal-classClassValueundefined CSS class (or classes) to apply to the '.modal' wrapper element
model-valuebooleanfalse Controls the visibility of the component
no-animationbooleanfalse When set, disables the animation
no-backdropbooleanfalse Disables rendering of the backdrop
no-close-on-backdropbooleanfalse Prevents closing the modal when clicking the backdrop outside the modal window
no-close-on-escbooleanfalse Prevents closing the modal by pressing the Esc key
no-fadebooleanfalse Alias for `noAnimation`
no-footerbooleanfalse Disables rendering of the modal footer
no-headerbooleanfalse Disables rendering of the header
no-header-closebooleanfalse Disables rendering of the header close button
no-stackingbooleanfalse
no-trapbooleanfalse Disables the focus trap feature
ok-classClassValueundefined CSS class (or classes) to apply to the '.modal-ok' button
ok-disabledbooleanfalse Places the built-in default footer OK button in a disabled state
ok-onlybooleanfalse Disables rendering of the default footer Cancel button
ok-titlestring'OK' Text to place in the default footer OK button
ok-variantButtonVariant | null'primary' Button color theme variant for the default footer OK button
scrollablebooleanfalse Enables scrolling of the modal body
showbooleanfalse When set, and prop 'visible' is false on mount, will animate from closed to open on initial mount. Mainly to help with template show. Use model-value for reactive show/hide
sizeSize | 'xl''md' Sets the modal's width. Options: 'sm', 'md' (default), 'lg', or 'xl'
teleport-disabledbooleanfalse Renders the modal where it is defined, disabling teleport
teleport-tostring | RendererElement | null | undefined'body' Overrides the default teleport location
titlestringundefined Text content for the modal title
title-classClassValueundefined CSS class (or classes) to apply to the modal title
title-tagstring'h5' HTML tag to render for the title instead of the default
title-visually-hiddenbooleanfalse Wraps the title in a '.visually-hidden' wrapper
trans-propsTransitionPropsundefined Transition properties
unmount-lazybooleanfalse When set and `lazy` is true, the content will be unmounted when closed
visiblebooleanfalse When 'true', open without animation
EventArgsDescription
backdrop
value: BvTriggerableEvent - The backdrop click event details
Emitted when the backdrop is clicked. Cancelable
cancel
value: BvTriggerableEvent - The Cancel button click event details
Emitted when the default footer Cancel button is clicked. Cancelable
close
value: BvTriggerableEvent - The close button click event details
Emitted when the default header close button is clicked. Cancelable
esc
value: BvTriggerableEvent - The Esc key press event details
Emitted when the Esc key is pressed. Cancelable
hidden
value: BvTriggerableEvent
Always emits after the component is hidden
hide
value: BvTriggerableEvent - Call value.preventDefault() to cancel hide
Always emits just before the component has hidden. Cancelable (as long as component wasn't forcibly hidden)
hide-prevented
value: BvTriggerableEvent
Emitted when the component tried to close, but was prevented from closing. This occurs when preventDefault() is called on the event, the user clicks escape and no-close-onbackdrop is set to true, or the user clicks on the backdrop and no-close-onbackdrop is set to true.
ok
value: BvTriggerableEvent - The OK button click event details
Emitted when the default footer OK button is clicked. Cancelable
show
value: BvTriggerableEvent - Call value.preventDefault() to cancel show
Always emits just before the component is shown. Cancelable
show-prevented
value: BvTriggerableEvent
Emitted when the component tried to open, but was prevented from opening. This occurs when preventDefault() is called on the event
shown
value: BvTriggerableEvent
Always emits just after component is shown.
toggle
value: BvTriggerableEvent - Call value.preventDefault() to cancel hide
Always emits just before the component is toggled via the exposed 'toggle()' function or useToggle composable . Cancelable (as long as component wasn't forcibly hidden)
toggle-prevented
value: BvTriggerableEvent
Emitted when the component tried to toggle, but was prevented from doing so. This occurs when preventDefault() is called on the event, the user clicks escape and no-close-onbackdrop is set to true, or the user clicks on the backdrop and no-close-onbackdrop is set to true.
update:model-value
value: boolean - The new value of the modal's visibility state
Emitted when the modal visibility changes
NameScopeDescription
backdropContent for the modal backdrop
cancel
cancel: Function - Closes the modal and fires the 'cancel' and 'hide' events, with `bvModalEvent.trigger = 'cancel'`
close: Function - Closes the modal and fires the 'close' and 'hide' events, with `bvModalEvent.trigger = 'headerclose'`
hide: Function - Accepts one argument 'trigger'. Closes the modal and fires the 'hide' event, with `bvModalEvent.trigger = trigger` (`trigger` is optional)
ok: Function - Closes the modal and fires the 'ok' and 'hide' events, with `bvModalEvent.trigger = 'ok'`
visible: boolean - The visibility state of the modal. 'true' if the modal is visible and 'false' if not visible
Content for the modal Cancel button. Optionally scoped
default
cancel: Function - Closes the modal and fires the 'cancel' and 'hide' events, with `bvModalEvent.trigger = 'cancel'`
close: Function - Closes the modal and fires the 'close' and 'hide' events, with `bvModalEvent.trigger = 'headerclose'`
hide: Function - Accepts one argument 'trigger'. Closes the modal and fires the 'hide' event, with `bvModalEvent.trigger = trigger` (`trigger` is optional)
ok: Function - Closes the modal and fires the 'ok' and 'hide' events, with `bvModalEvent.trigger = 'ok'`
visible: boolean - The visibility state of the modal. 'true' if the modal is visible and 'false' if not visible
Content for the modal body. Optionally scoped
footer
cancel: Function - Closes the modal and fires the 'cancel' and 'hide' events, with `bvModalEvent.trigger = 'cancel'`
close: Function - Closes the modal and fires the 'close' and 'hide' events, with `bvModalEvent.trigger = 'headerclose'`
hide: Function - Accepts one argument 'trigger'. Closes the modal and fires the 'hide' event, with `bvModalEvent.trigger = trigger` (`trigger` is optional)
ok: Function - Closes the modal and fires the 'ok' and 'hide' events, with `bvModalEvent.trigger = 'ok'`
visible: boolean - The visibility state of the modal. 'true' if the modal is visible and 'false' if not visible
Content for the modal footer. Removes default OK and Cancel buttons. Optionally scoped
header
cancel: Function - Closes the modal and fires the 'cancel' and 'hide' events, with `bvModalEvent.trigger = 'cancel'`
close: Function - Closes the modal and fires the 'close' and 'hide' events, with `bvModalEvent.trigger = 'headerclose'`
hide: Function - Accepts one argument 'trigger'. Closes the modal and fires the 'hide' event, with `bvModalEvent.trigger = trigger` (`trigger` is optional)
ok: Function - Closes the modal and fires the 'ok' and 'hide' events, with `bvModalEvent.trigger = 'ok'`
visible: boolean - The visibility state of the modal. 'true' if the modal is visible and 'false' if not visible
Content for the modal header. Removes the top-right close button. Optionally scoped
header-closeContent for the modal header close button. Not shown if the 'header' slot is used
ok
cancel: Function - Closes the modal and fires the 'cancel' and 'hide' events, with `bvModalEvent.trigger = 'cancel'`
close: Function - Closes the modal and fires the 'close' and 'hide' events, with `bvModalEvent.trigger = 'headerclose'`
hide: Function - Accepts one argument 'trigger'. Closes the modal and fires the 'hide' event, with `bvModalEvent.trigger = trigger` (`trigger` is optional)
ok: Function - Closes the modal and fires the 'ok' and 'hide' events, with `bvModalEvent.trigger = 'ok'`
visible: boolean - The visibility state of the modal. 'true' if the modal is visible and 'false' if not visible
Content for the modal OK button. Optionally scoped
title
cancel: Function - Closes the modal and fires the 'cancel' and 'hide' events, with `bvModalEvent.trigger = 'cancel'`
close: Function - Closes the modal and fires the 'close' and 'hide' events, with `bvModalEvent.trigger = 'headerclose'`
hide: Function - Accepts one argument 'trigger'. Closes the modal and fires the 'hide' event, with `bvModalEvent.trigger = trigger` (`trigger` is optional)
ok: Function - Closes the modal and fires the 'ok' and 'hide' events, with `bvModalEvent.trigger = 'ok'`
visible: boolean - The visibility state of the modal. 'true' if the modal is visible and 'false' if not visible
Content for the modal title. Not shown if the 'header' slot is used. Optionally scoped