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
<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.
<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.
<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
.
<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.
<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
<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
Modal message boxes
If you're looking for replacements for $bvModal.msgBoxOk
and $bvModal.msgBoxConfirm
please see the migration guide
Component Reference
<BModal>
Prop | Type | Default | Description |
---|---|---|---|
autofocus | boolean | true | 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-first | boolean | false | Animate the backdrop before the modal, and on leave animate the modal before the backdrop |
body | string | undefined | |
body-attrs | Readonly<AttrsValue> | undefined | |
body-bg-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the body background |
body-class | ClassValue | null | CSS class (or classes) to apply to the '.modal-body' wrapper element |
body-scrolling | boolean | false | Enables/disables scrolling the body while modal is open |
body-text-variant | TextColorVariant | null | null | Applies one of the Bootstrap theme color variants to the body text |
body-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the body (this takes priority over bodyBgVariant and bodyTextVariant) |
busy | boolean | false | Places the built in default footer OK and Cancel buttons in the disabled state |
button-size | Size | 'md' | |
cancel-disabled | boolean | false | Places the built in default footer Cancel button in the disabled state |
cancel-title | string | 'Cancel' | Text string to place in the default footer Cancel button |
cancel-variant | ButtonVariant | null | 'secondary' | Variant to use for the default footer Cancel button |
centered | boolean | false | Vertically centers the modal in the viewport |
content-class | ClassValue | undefined | CSS class (or classes) to apply to the '.modal-content' wrapper element |
dialog-class | ClassValue | undefined | CSS class (or classes) to apply to the '.modal-dialog' wrapper element |
footer-bg-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the footer background |
footer-border-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the footer border |
footer-class | ClassValue | undefined | CSS class (or classes) to apply to the '.modal-footer' wrapper element |
footer-text-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the footer text |
footer-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the footer (this takes priority over footerBgVariant and footerTextVariant) |
fullscreen | boolean | Breakpoint | false | 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-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the header background |
header-border-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the header border |
header-class | ClassValue | undefined | CSS class (or classes) to apply to the '.modal-header' wrapper element |
header-close-class | ClassValue | undefined | CSS class (or classes) to apply to the header close button |
header-close-label | string | 'Close' | Accessibility label for the header close button |
header-close-variant | ButtonVariant | null | 'secondary' | Applies a variant to the header close button when the header close button uses the header-close slot |
header-text-variant | TextColorVariant | null | null | Applies one of the Bootstrap theme color variants to the header text |
header-variant | ColorVariant | null | null | Applies one of the Bootstrap theme color variants to the header (this takes priority over headerBgVariant and headerTextVariant) |
id | string | undefined | Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed |
initial-animation | boolean | false | When set, enables the initial animation on mount |
lazy | boolean | false | When set, the content will not be mounted until opened |
modal-class | ClassValue | undefined | CSS class (or classes) to apply to the '.modal' wrapper element |
model-value | boolean | false | Controls the visibility of the component |
no-animation | boolean | false | When set, disables the animation |
no-backdrop | boolean | false | Disables rendering of the backdrop |
no-close-on-backdrop | boolean | false | Disables closing the modal when clicking on the modal backdrop (outside the modal window) |
no-close-on-esc | boolean | false | Disables the ability to close the modal by pressing the ESC key |
no-fade | boolean | false | Alias for `noAnimation` |
no-footer | boolean | false | Disables rendering of the modal footer |
no-header | boolean | false | Disables rendering of the header |
no-header-close | boolean | false | Disables rendering of the header close button |
no-stacking | boolean | false | |
no-trap | boolean | false | Disables the focus trap feature |
ok-disabled | boolean | false | Places the built in default footer OK button in the disabled state |
ok-only | boolean | false | Disables rendering of the default footer Cancel button |
ok-title | string | 'OK' | Text string to place in the default footer OK button |
ok-variant | ButtonVariant | null | 'primary' | Button color theme variant to apply to the default footer OK button |
scrollable | boolean | false | Enables scrolling of the modal body |
show | boolean | false | 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 |
size | Size | 'xl' | 'md' | Set the size of the modal's width. 'sm', 'md' (default), 'lg', or 'xl' |
teleport-disabled | boolean | false | Renders the modal in the exact place it was defined |
teleport-to | string | RendererElement | null | undefined | 'body' | Overrides the default teleport location |
title | string | undefined | Text content to place in the title |
title-class | ClassValue | undefined | CSS class (or classes) to apply to the title |
title-tag | string | 'h5' | Specify the HTML tag to render instead of the default tag for the title |
title-visually-hidden | boolean | false | Wraps the title in an '.visually-hidden' wrapper |
trans-props | TransitionProps | undefined | Transition properties |
unmount-lazy | boolean | false | When set and `lazy` is true, the content will be unmounted when closed |
visible | boolean | false | When 'true', open without animation |
Event | Args | Description |
---|---|---|
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-prevented | Emitted 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-prevented | Emitted 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 |
Name | Scope | Description |
---|---|---|
backdrop | Modal 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-close | Content 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 |