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>
<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
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 |
---|---|---|---|
backdrop-first | boolean | false | Animates the backdrop before the modal and, on leave, animates 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 or disables scrolling the body while the modal is open |
body-text-variant | ColorVariant | 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 (takes priority over bodyBgVariant and bodyTextVariant) |
busy | boolean | false | Places the built-in default footer OK and Cancel buttons in a disabled state |
button-size | Size | 'md' | |
cancel-class | ClassValue | undefined | CSS class (or classes) to apply to the '.modal-cancel' button |
cancel-disabled | boolean | false | Places the built-in default footer Cancel button in a disabled state |
cancel-title | string | 'Cancel' | Text to place in the default footer Cancel button |
cancel-variant | ButtonVariant | null | 'secondary' | Variant 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 |
focus | 'ok' | 'cancel' | 'close' | string | ComponentPublicInstance | HTMLElement | null | undefined | 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-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 (takes priority over footerBgVariant and footerTextVariant) |
fullscreen | boolean | Breakpoint | false | 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-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' | Variant for the header close button when using the header-close slot |
header-text-variant | ColorVariant | 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 (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 | Prevents closing the modal when clicking the backdrop outside the modal window |
no-close-on-esc | boolean | false | Prevents closing 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-class | ClassValue | undefined | CSS class (or classes) to apply to the '.modal-ok' button |
ok-disabled | boolean | false | Places the built-in default footer OK button in a disabled state |
ok-only | boolean | false | Disables rendering of the default footer Cancel button |
ok-title | string | 'OK' | Text to place in the default footer OK button |
ok-variant | ButtonVariant | null | 'primary' | Button color theme variant for 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' | Sets the modal's width. Options: 'sm', 'md' (default), 'lg', or 'xl' |
teleport-disabled | boolean | false | Renders the modal where it is defined, disabling teleport |
teleport-to | string | RendererElement | null | undefined | 'body' | Overrides the default teleport location |
title | string | undefined | Text content for the modal title |
title-class | ClassValue | undefined | CSS class (or classes) to apply to the modal title |
title-tag | string | 'h5' | HTML tag to render for the title instead of the default |
title-visually-hidden | boolean | false | Wraps the title in a '.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 - 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 |
Name | Scope | Description |
---|---|---|
backdrop | Content 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-close | Content 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 |