Currently viewing documentation for version 5.1.0. Other versions: 4.x · 3.x

* indicates options added in 5.0.

Important:

There are some caveats to using Bootbox dialogs in place of native dialogs. Please see the Known Limitations section to learn more.

A simple alert dialog with a single button. Pressing the ESC key or clicking the close button dismisses the dialog.

Basic Usage

This is the simplest usage of Bootbox, requiring only the text of the message you wish to show.

bootbox.alert("Your message here…")
Example bb.1
Your message here…

Your message can also contain HTML.

bootbox.alert("Your message <b>here…</b>")
Example bb.2
Your message here…

Advanced Usage

If you have code that should not be evaluated until the user has dismissed the alert (see Bootbox Limitations below), call it within the callback function:

bootbox.alert("Your message here…", function(){
    /* your callback code */ 
})

Alerts can be customized, using the options described below. Here's an example of a small alert, using size:

bootbox.alert({
    size: "small",
    title: "Your Title",
    message: "Your message here…",
    callback: function(){ /* your callback code */ }
})
Example bb.3
Your Title
Your message here…

Requires Bootstrap 3.1.0 or newer.

A confirm dialog with a cancel and a confirm button. Pressing the ESC key or clicking close () dismisses the dialog and invokes the callback as if the user had clicked the Cancel button.

Confirm dialogs require a callback function.

Basic Usage

The simplest method of using the confirm() dialog requires the text of the message you wish to show and a callback to handle the user's selection. The callback function is passed a value of true or false, depending on which button the user pressed.

bootbox.confirm("Are you sure?", function(result){
    /* your callback code */ 
})
Example bb.4
Are you sure?
Please note:

All Bootstrap modals, unlike native alerts, confirms, or prompts, are non-blocking. Keep that in mind when using the confirm() dialog, as it is not a drop-in replacement for native confirm dialogs. Any code that depends on the user's selection must be placed in the callback function.

Advanced Usage

Confirm dialogs can be customized, using the options described below. Here's an example of a small confirm, using size:

bootbox.confirm({ 
    size: "small",
    message: "Are you sure?",
    callback: function(result){ /* result is a boolean; true = OK, false = Cancel*/ }
})
Example bb.5
Are you sure?

Requires Bootstrap 3.1.0 or newer.

A dialog which prompts for user input. Pressing the ESC key or clicking close () dismisses the dialog and invokes the callback as if the user had clicked the Cancel button.

Prompt dialogs require a callback function.

Basic Usage

The simplest usage of the prompt() dialog requires the text of the message you wish to show and a callback to handle the user's input. The value entered will be null if the user cancelled or dismissed the dialog; otherwise it is passed the value of the text input.

bootbox.prompt("What is your name?", function(result){
    /* your callback code */ 
})
Example bb.6
What is your name?
Please note:

All Bootstrap modals, unlike native alerts, confirms, or prompts, are non-blocking. Keep that in mind when using the prompt() dialog, as it is not a drop-in replacement for native prompt dialogs. Any code that depends on the user's input must be placed in the callback function.

Advanced Usage

Prompt dialogs can also be customized, using the options described below. Here's an example of a small prompt, using size:

bootbox.prompt({ 
    size: "small",
    title: "What is your name?",
    callback: function(result){ 
        /* result = String containing user input if OK clicked or null if Cancel clicked */ 
    }
});
Example bb.7
What is your name?

Requires Bootstrap 3.1.0 or newer.

Please note:

Prompt requires the title option (when using the options object). You may use the message option, but the prompt result will not include any form values from your message.

Prompt Dialog Options

Prompt dialogs are (by default) single-line text inputs. You can modify the type of prompt Bootbox generates using the prompt-only options below.

value

Type: String | Number | Array

You can set the initial value of the prompt using the value option.

To pre-select more than one value (when using the checkbox or multiple select type), use an array for the value option. Note that the type of each item should match the type from inputOptions.

Default: null

inputType

Type: String

Changes the type of input generated for the prompt dialog.

To pre-select more than one value (when using the checkbox or multiple select type), use an array for the value option. Note that the type of each item should match the type from inputOptions.

Valid values, with their class selectors:

Name Class
text (default) bootbox-input-text
password bootbox-input-password
textarea bootbox-input-textarea
email bootbox-input-email
select bootbox-input-select
checkbox bootbox-input-checkbox
radio * bootbox-input-radio
date bootbox-input-date
time bootbox-input-time
number bootbox-input-number
range * bootbox-input-range

Additionally, checkbox and radiobuttons are wrapped in a parent element, bootbox-checkbox-list and bootbox-radiobutton-list, respectively.

email, date, time, number, and range all require browser support to function properly. You may want to consult caniuse.com to determine if your target browsers support the input types you are intending to use.

Date input type and browser support

At the time this is written, every major browser which supports the date input type will only accept date values in the ISO 8601 format, which (for a complete date) is YYYY-MM-DD, where

YYYY = four-digit year
MM   = two-digit month (01=January, etc.)
DD   = two-digit day of month (01 through 31)

See https://en.wikipedia.org/wiki/ISO_8601

Range input and default value

Please note that, when using the range input type, the default min value is 0 and the default max value is 100 (see MDN). If you attempt to set the default value to something outside the min or max values, the input will default to the respective value.

Default: text

inputOptions

Type: Array

If you specify select, checkbox, or radio as the input type, you must also supply an array of valid values in the format of:

{
    text: '',
    value: '',
    group: ''
}

group is an optional property for populating the <select>; if specified, <optgroup> elements will be generated for each group value found in the inputOptions array.

Default: null

min, max *

Type: String | Number | Date String | Time string

The min or max value for the <input> element. Only valid for date, time, number, and range types.

For range and number, min/max must be a numeric value.

For time, min/max must a valid partial time value, in the form of HH:MM:SS, where

HH = any zero-padded value between 00 and 23
MM = any zero-padded value between 00 and 59
SS = any zero-padded value between 00 and 59

For date, min/max must a date value in the form of YYYY-MM-DD, where

YYYY = four-digit year
MM   = two-digit month (01=January, etc.)
DD   = two-digit day of month (01 through 31)

See the MDN article for min or max for more information.

step *

Type: String | Number

The step value for the <input> element. Only valid for time, number, and range types.

Can be the string value any (the browser default), or a positive, non-zero numeric value. See the MDN article for <input> for more information.

Warning: For most browsers, date inputs are buggy in their implementation of step, so this attribute would likely have no effect. Therefore, we don't set the step attribute for date inputs.

See the MDN article for more information.

maxlength

Type: Number

Set the maxlength option to limit the number of characters entered into a text-based input. Must be a positive, non-zero numeric value.

Valid for text, textarea, email, and password

pattern

Type: String

Set the pattern option to require the input value to follow a specific format. If pattern is set and a value has been entered by your user, the prompt will not close if the input value fails pattern validation.

Can be added for any input type, but generally only used for text inputs, normally as a fallback for email, time, date, number or range inputs where native browser support for those types is lacking.

placeholder

Type: String

Set the placeholder option to provide a small amount of "helper" text within a text-based input.

There is no real limit on the amount of text you may use for your placeholder, but keep in mind that the placeholder disappears when the input has focus (depending on the browser) or has a value. Use the message option to provide help text which you want to always be visible or that is important.

Valid for text, textarea, email, and password.

If specified for time, date, number, or range inputs, your users will normally only see the placeholder where native browser support for those types is lacking.

required *

Type: Boolean

Set the required option to true to require an input value. When true, the prompt will not close if the input value is null, an empty string, or fails the input type's built-in validation constraints.

Valid for text, textarea, email, password, select, time, date, number, and range types.

multiple *

Type: Boolean

Set the multiple option to true to allow users to select more than one option when using the select input type.

To pre-select more than one value, use an array for the value option. Note that the type of each item should match the type from inputOptions.

Valid only for the select type.

rows *

Type: Number

Set the rows option to a non-zero number to set the rows attribute when using the textarea input type. If omitted, the rows attribute is not set and the textarea will render with the browser's default number of rows.

Valid only for the textarea type.

Please see the Examples page for more examples of prompt dialogs.

A completely customisable dialog method which takes a single argument - an options object.

Custom dialogs do not close automatically when the ESC key is pressed; you must implement this behavior yourself using the onEscape option.

Basic Usage

The minimum required to create a custom dialog is the message option, which will create a non-dismissable dialog (useful as a "loading" overlay).

bootbox.dialog({ 
    message: '<div class="text-center"><i class="fa fa-spin fa-spinner"></i> Loading...</div>', 
    closeButton: false 
})
Example bb.8
Loading...

Advanced Usage

As noted above, the only required option for a custom dialog is message. Also, custom dialogs do not utilize a global callback; each button you add should have it's own callback function. Here's an example with many of the options utilized:

bootbox.dialog({ 
    title: 'Custom Dialog Example',
    message: '<p>This dialog demonstrates many of the options available when using the Bootbox library</p>',
    size: 'large',
    onEscape: true,
    backdrop: true,
    buttons: {
        fee: {
            label: 'Fee',
            className: 'btn-primary',
            callback: function(){
                                
            }
        },
        fi: {
            label: 'Fi',
            className: 'btn-info',
            callback: function(){
                                
            }
        },
        fo: {
            label: 'Fo',
            className: 'btn-success',
            callback: function(){
                                
            }
        },
        fum: {
            label: 'Fum',
            className: 'btn-danger',
            callback: function(){
                                
            }
        }
    }
})
Example bb.9
Custom Dialog Example

This dialog demonstrates many of the options available when using the Bootbox library

Please see the Examples page for more examples of custom dialogs.

Bootbox dialogs can be configured using the options below.

message

Type: String | Element

Required for alert, confirm, and custom dialogs

Text (or markup ) displayed in the dialog.

title

Type: String | Element

Required for prompt

Adds a header to the dialog and places this text (or markup ) in an <h5> element.

callback

Type: Function

Required for confirm and prompt Not called for custom dialogs

An alert callback should not supply an argument; it will be ignored if it does:

bootbox.alert({ 
    message: "I'm an alert!", 
    callback: function() {
    } 
})

Confirm and prompt callbacks must supply an argument for the result; for confirm, it will be a true or false value, while the prompt result will hold the value(s) entered by the user:

bootbox.confirm("Are you sure?", function(result) {
    // result will be true or false
}); 

or

bootbox.prompt("What is your name?", function(result) {
    if (result === null) {
        // Prompt dismissed
    } else {
        // result has a value
    }
}); 

For any callback, if you do not want the dialog to close when the callback completes, add return false; as the last line of the callback. You will then need to manually dismiss the dialog using the modal() function or bootbox.hideAll():

var dialog = bootbox.prompt("What is your name?", function(result) {
    if (result === null) {
        // Prompt dismissed
    } else {
        // result has a value
        dialog.modal('hide');
    } 

    return false;
}); 

Default: null

onEscape

Type: Boolean | Function

Allows the user to dismiss the dialog by hitting ESC, which will invoke this function.

Options:
Undefined (null) No callback function has been provided.
true Hitting the ESC dismisses the dialog.
false Hitting the ESC does not dismiss the dialog.

Default: true for alert, confirm, and prompt; null for custom dialogs.

show

Type: Boolean

Whether the dialog should be shown immediately.

Default: true

backdrop

Type: Boolean

Whether the dialog should be have a backdrop or not. Also determines whether clicking on the backdrop dismisses the modal.

Options:
Undefined (null) The backdrop is displayed, but clicking on it has no effect.
true * The backdrop is displayed, and clicking on it dismisses the dialog.
false The backdrop is not displayed.

Default: null

* When this value is set to true, the dialog will only dismiss when onEscape is also set to true or some callback function.

closeButton

Type: Boolean

Whether the dialog should have a close button () or not.

Default: true

animate

Type: Boolean

Animate the dialog in and out (requires a browser which supports CSS animations).

Default: true

className

Type: String

An additional class to apply to the dialog wrapper.

Default: null

size

Type: String

Adds the relevant Bootstrap modal size class to the dialog wrapper. Valid values are:

Small 'small', 'sm'
Large 'large', 'lg'
Extra large 'extra-large', 'xl'

Requires Bootstrap 3.1.0 or newer. Extra-large requires Bootstrap 4.2.0 or newer.

Default: null

locale *

Type: String

Sets the locale to use per dialog — this option does not override the default locale. Other dialogs will still use the default locale.

The locale settings are used to translate the three standard button labels: OK, CONFIRM, CANCEL

See the note on locales below.

buttons

Type: Object

Buttons are defined as JavaScript objects. The minimum shortform requirement to define a button is:

"Your button text": function() { }

The complete definition of a button object is:

buttonName : {
    label: 'Your button text',
    className: 'some-class',
    callback: function() { 
    }
}
Options:
alert ok
confirm cancel, confirm
prompt cancel, confirm

Each of the available button options can be overridden to use custom content (text or HTML ) and CSS styles. For example:

bootbox.confirm({
    message: "This is a confirm with custom button text and color! Do you like it?",
    buttons: {
        confirm: {
            label: 'Yes',
            className: 'btn-success'
        },
        cancel: {
            label: 'No',
            className: 'btn-danger'
        }
    },
    callback: function (result) {
        // ...
    }
});

You cannot override the callbacks for the alert, confirm, and prompt dialog's buttons.

swapButtonOrder *

Type: Boolean

Flips the order in which the buttons are rendered, from cancel/confirm to confirm/cancel.

Default: false

centerVertical *

Type: Boolean

If true, the modal-dialog-centered class will be added to the dialog wrapper.

Requires Bootstrap 4.1.0 or newer.

Default: false

scrollable

Type: Boolean

If true, the modal-dialog-scrollable class will be added to the dialog wrapper. Enable this option to have the content of long modals automatically scroll.

Requires Bootstrap 4.3.0 or newer.

Default: false

Locales are used to provide a translation for each of the built-in command buttons (OK, CANCEL, and CONFIRM).

The following locales are available (see the table below). You can find each of these locales rendered on the Examples page.

Key Name Key Name
ar Arabic az Azerbaijani
bg_BG Bulgarian br Portuguese - Brazil
cs Czech da Danish
de German el Greek
en English es Spanish / Español
et Estonian eu Basque
fa Farsi / Persian fi Finnish
fr French / Français he Hebrew
hr Croatian hu Hungarian
id Indonesian it Italian
ja Japanese ko Korean
lt Lithuanian lv Latvian
nl Dutch no Norwegian
pl Polish pt Portuguese
ru Russian sk Slovak
sl Slovenian sq Albanian
sv Swedish sw Swahili
ta Tamil th Thai
tr Turkish uk Ukrainian
zh_CN Chinese (People's Republic of China) zh_TW Chinese (Taiwan / Republic of China)
Please note:

To use any locale other than en, you must do one of the following:

  • Use the bootbox.all.js or bootbox.all.min.js file, which includes all locales.
  • Add a reference to bootbox.locales.js or bootbox.locales.min.js after bootbox.js.
  • Add a reference to the target locale file (fr.js to use the French locale, for example), found in the src/locales directory.
  • Add the locale manually, using the addLocale function.

The Bootbox object returned from each of the dialog functions is a jQuery object. As such, you can chain most jQuery functions onto the result of a Bootbox dialog. Here's an example showing how to handle Bootstrap's shown.bs.modal event, using .on():

var dialog = bootbox.dialog({
    /* Your options... */
});
                
dialog.on('shown.bs.modal', function(e){
    // Do something with the dialog just after it has been shown to the user...
});

If you set the show option to false, you can also use Bootstrap's modal() function to show and hide your dialog manually:

var dialog = bootbox.dialog({
    show: false,
    /* Your options... */
});
                
dialog.modal('show');
                
dialog.modal('hide');

The following functions can be called on an instance of a Bootbox object.

bootbox.init(function)

Allows the user to supply a function to be called when the dialog gets initialized.

var dialog = bootbox.dialog({
    /* Your options... */
});
                
dialog.init(function(){
    // Do something with the dialog...
});

init can be called on any of the wrapper functions, as they all return a Bootbox/jQuery object.

The following functions can be called statically.

bootbox.setDefaults(object options)

This method allows the user to set many of the default options shown in the dialog example. Many of these options are also applied to the basic wrapper methods and can be overridden whenever the wrapper methods are invoked with a single options argument:

bootbox.setLocale(String name)

Allows the user to select a locale rather than using setDefaults("locale", ...).

The locale settings are used to translate the three standard button labels: OK, CONFIRM, CANCEL

Default: en

bootbox.addLocale(String name, object values)

Allows the user to add a custom translation for each of the built-in command buttons. The values object should be in this format:

{
    OK : '',
    CANCEL : '',
    CONFIRM : ''
}

bootbox.removeLocale(String name)

Allows the user to remove a locale from the available locale settings.

bootbox.locales(String name)

Allows the user to get a locale object from the available locale settings. If name is empty, all locales will be returned.

bootbox.hideAll()

Hide all currently active Bootbox dialogs. Individual dialogs can be closed as per normal Bootstrap dialogs:

dialog.modal('hide')

Using Bootbox has some caveats, as noted below.

Dialog code does not block code execution

All Bootstrap modals (and therefore Bootbox modals), unlike native alerts, confirms, or prompts, are asynchronous; meaning, the events which Bootstrap generates are non-blocking events. Because of this limitation, code that should not be evaluated until a user has dismissed your dialog must be called within the callback function of the dialog.

Multiple open modals are not supported

This is a limitation of the Bootstrap modal plugin, as noted in the official Bootstrap documentation. While it is functionally possible to trigger multiple modals, custom CSS and/or JavaScript code is required for each layer of modal to display properly.

Prompt values are not sanitized

The value(s) returned by a Bootbox prompt are not sanitized in any way.

Content strings are not sanitized

You can use either plain text or HTML for pretty much any Bootbox option which sets a display aspect of the rendered modal, such as the title, message, and button labels. Bootbox does not sanitize any of these values. Since we use jQuery's .html() function to build the dialog, this is a possible XSS vector. It is your responsibility to sanitize your content.