Documentation

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

Alert

bootbox.alert(string|element message, [function callback]);

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…

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 */
                            });

Formatted text

Your message can also contain HTML.

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

You can also pass a reference to a jQuery-selected element.

<div id="message-template">Your message
                              <b>here…</b></div>
                              <script>
                              let template = $('#message-template');
                              bootbox.alert(template);
                              </script>
Example bb.2b
Your message here…

Advanced Usage

bootbox.alert(object options);

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.


Confirm

bootbox.confirm(string|element message, function callback);

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 bootbox.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 bootbox.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

bootbox.confirm(object options);

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.


Prompt

bootbox.prompt(string|element title, function callback);

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 bootbox.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 bootbox.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

bootbox.prompt(object options);

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: StringNumberArray

Default: null

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.

inputType

Type: String

Default: text

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 short 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 of the input to something less than your min value or greater than your max value, the input will default to the respective value.

inputOptions

Type: Array

Default: null

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.

min, max

Type: StringNumberDate StringTime string

Default: null

Types: date, time, number, range

The min or max value for the <input> element.

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.

Number input and min/max values

When using the number input type, note that a value may be manually entered which is less than your min or greater than your max (MDN). The input will, however, report that it is invalid, which can be used in conjunction with the required option to prevent the value from being accepted.

step

Type: StringNumber

Default: null

Types: time, number, range

The step value for the <input> element.

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.

The default step value for number inputs is 1 (MDN).

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

Default: null

Types: text, textarea, email, password

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

pattern

Type: String

Default: null

Types: All, except select, radio, checkbox

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 as a fallback for email, time, date, number or range inputs where native browser support for those types is lacking.

placeholder

Type: String

Default: null

Types: All *

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.

* 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. We also will set the placeholder attribute on a select, although that's not a valid/supported attribute.

required

Type: Boolean

Default: null

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.

If used with the checkbox inputType, each checkbox must be checked for the prompt to be valid.

multiple

Type: Boolean

Default: null

Types: select

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.

rows

Type: Number

Default: null

Types: textarea

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.

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


Custom Dialog

bootbox.dialog(object options);

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

Note: onEscape

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.

Here's an example using message and closeButton: false, which will create a non-dismissable dialog (useful as a "loading" overlay).

bootbox.dialog({
                              message: '<div class="text-center"><i class="fas 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(){

                              }
                              },
                              fie: {
                              label: 'Fie',
                              className: 'btn-info',
                              callback: function(){

                              }
                              },
                              foe: {
                              label: 'Foe',
                              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.


Dialog Options

The options shown below apply to all Bootbox dialogs. Options which are specific to prompt dialogs can be found above.

message

Type: StringElement

Default: null

Required for alert, confirm, and custom dialogs

Text (or markup ) displayed in the dialog.

title

Type: StringElement

Default: null

Required for prompt

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

callback

Type: Function

Default: null

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():

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

                            return false;
                            });
onEscape

Type: BooleanFunction

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

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.
onShow

Type: Function

Default: null

Use onShow to bind a callback function to the show.bs.modal event, which is called just before the modal is shown. See the Bootstrap docs for more information.

bootbox.alert({
                            message: "I'm an alert!",
                            onShow: function(e) {
                            /* e is the show.bs.modal event */
                            }
                            })

Requires Bootbox 5.4.0 or newer.

onShown

Type: Function

Default: null

Use onShown to bind a callback function to the shown.bs.modal event, which is called just after the modal is shown. See the Bootstrap docs for more information.

bootbox.alert({
                            message: "I'm an alert!",
                            onShown: function(e) {
                            /* e is the shown.bs.modal event */
                            }
                            })

Requires Bootbox 5.4.0 or newer.

onHide

Type: Function

Default: null

Use onHide to bind a callback function to the hide.bs.modal event, which is called just before the modal is hidden. See the Bootstrap docs for more information.

bootbox.alert({
                            message: "I'm an alert!",
                            onHide: function(e) {
                            /* e is the hide.bs.modal event */
                            }
                            })

Requires Bootbox 5.4.0 or newer.

onHidden

Type: Function

Default: null

Use onHidden to bind a callback function to the hidden.bs.modal event, which is called just after the modal is hidden. See the Bootstrap docs for more information.

bootbox.alert({
                            message: "I'm an alert!",
                            onHidden: function(e) {
                            /* e is the hidden.bs.modal event */
                            }
                            })

Requires Bootbox 5.4.0 or newer.

show

Type: Boolean

Default: true

Whether the dialog should be shown immediately.

backdrop

Type: Boolean

Default: null

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.

* 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

Default: true

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

animate

Type: Boolean

Default: true

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

className

Type: String

Default: null

An additional class to apply to the dialog wrapper.

size

Type: String

Default: null

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.

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

Default: false

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

centerVertical

Type: Boolean

Default: false

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

Requires Bootstrap 4.1.0 or newer.

scrollable

Type: Boolean

Default: false

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.


Available Locales

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

Locales Index

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

Key Name
ar Arabic
az Azerbaijani
bg-BG Bulgarian
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
ka Georgian
ko Korean
lt Lithuanian
lv Latvian
nl Dutch
no Norwegian
pl Polish
pt Portuguese
pt-BR Portuguese - Brasil
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)

Using Locales

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.

Using jQuery Functions with Bootbox

Basic Usage

The 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():

let 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:

let dialog = bootbox.dialog({
                            show: false,
                            /* Your options... */
                            });

                            dialog.modal('show');

                            dialog.modal('hide');

Instance Functions

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

init()

.init(function handler);

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

let 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 jQuery object.


Global Functions

The following functions are called statically, using the bootbox global.

setDefaults()

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.setDefaults({
                            /**
                            * @optional String
                            * @default: en
                            * which locale settings to use to translate the three
                            * standard button labels: OK, CONFIRM, CANCEL
                            */
                            locale: 'fr',

                            /**
                            * @optional Boolean
                            * @default: true
                            * whether the dialog should be shown immediately
                            */
                            show: true,

                            /**
                            * @optional Boolean
                            * @default: true
                            * whether the dialog should be have a backdrop or not
                            */
                            backdrop: true,

                            /**
                            * @optional Boolean
                            * @default: true
                            * show a close button
                            */
                            closeButton: true,

                            /**
                            * @optional Boolean
                            * @default: true
                            * animate the dialog in and out (not supported in < IE 10) */ animate: true, /** * @optional
                              String * @default: null * an additional class to apply to the dialog wrapper */
                              className: 'my-modal' });
                        

setLocale()

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

addLocale()

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 must be in this format:

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

removeLocale()

bootbox.removeLocale(String name);

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

locales()

bootbox.locales([String name]);

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

hideAll()

bootbox.hideAll();

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

dialog.modal('hide');

Known Limitations

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.

We heartily recommend reviewing the OWASP Guidelines for preventing XSS. For library recommendations, skip to Rule 6 - Sanitize HTML Markup with a Library Designed for the Job.