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>
  </BModal>
</template>

<script setup lang="ts">
const nestedModal1 = ref(false)
const nestedModal2 = ref(false)
const nestedModal3 = ref(false)
</script>

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
autofocusbooleantrue When set to 'false', disables auto focusing the modal when opened
autofocus-button'ok' | 'cancel' | 'close'undefined Specify which built-in button to focus once the modal opens: 'ok', 'cancel', or 'close'
backdrop-firstbooleanfalse Animate the backdrop before the modal, and on leave animate 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/disables scrolling the body while modal is open
body-text-variantTextColorVariant | 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 (this takes priority over bodyBgVariant and bodyTextVariant)
busybooleanfalse Places the built in default footer OK and Cancel buttons in the disabled state
button-sizeSize'md'
cancel-disabledbooleanfalse Places the built in default footer Cancel button in the disabled state
cancel-titlestring'Cancel' Text string to place in the default footer Cancel button
cancel-variantButtonVariant | null'secondary' Variant to use 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
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 (this takes priority over footerBgVariant and footerTextVariant)
fullscreenboolean | Breakpointfalse A boolean value will enable/disable full screen mode. A Breakpoint value will set the breakpoint to enable full screen mode below the value of the breakpoint. Breakpoint values are: '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' Applies a variant to the header close button when the header close button uses the header-close slot
header-text-variantTextColorVariant | 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 (this 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 Disables closing the modal when clicking on the modal backdrop (outside the modal window)
no-close-on-escbooleanfalse Disables the ability to close 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-disabledbooleanfalse Places the built in default footer OK button in the disabled state
ok-onlybooleanfalse Disables rendering of the default footer Cancel button
ok-titlestring'OK' Text string to place in the default footer OK button
ok-variantButtonVariant | null'primary' Button color theme variant to apply to 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' Set the size of the modal's width. 'sm', 'md' (default), 'lg', or 'xl'
teleport-disabledbooleanfalse Renders the modal in the exact place it was defined
teleport-tostring | RendererElement | null | undefined'body' Overrides the default teleport location
titlestringundefined Text content to place in the title
title-classClassValueundefined CSS class (or classes) to apply to the title
title-tagstring'h5' Specify the HTML tag to render instead of the default tag for the title
title-visually-hiddenbooleanfalse Wraps the title in an '.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
Emitted when the backdrop is clicked. Cancelable
cancel
value: BvTriggerableEvent
Emitted when the default footer cancel button is clicked. Cancelable
close
value: BvTriggerableEvent
Emitted when the default header close button is clicked. Cancelable
esc
value: BvTriggerableEvent
Emitted when the esc keyboard button is clicked. Cancelable
hidden
value: BvTriggerableEvent
Always emits after modal is hidden
hide
value: BvTriggerableEvent
Always emits just before modal has hidden. Cancelable (as long as modal wasn't forcibly hidden)
hide-preventedEmitted when the modal 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
Emitted when the default footer ok button is clicked. Cancelable
show
value: BvTriggerableEvent
Always emits just before modal is shown. Cancelable
show-preventedEmitted when the modal tried to open, but was prevented from opening. This occurs when preventDefault() is called on the event
shown
value: BvTriggerableEvent
Always emits just after modal is shown. Cancelable
update:model-value
value: boolean - The new value of the modal's visible state
Emitted when modal visibility changes
NameScopeDescription
backdropModal Backdrop content
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 the `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
Modal CANCEL button content. 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 the `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 of 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 the `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
Modal footer content. Also 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 the `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
Entire modal header container contents. Also removes the top right X close button. Optionally scoped
header-closeContent of Modal header close button. If 'header' slot is used, this slot will not be shown
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 the `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
Modal OK button content. 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 the `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
Modal title. If 'header' slot is used, this slot will not be shown. Optionally scoped