Documentation
Currently viewing documentation for version 6.0.0. Other versions: 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…');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>');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>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 */ }
});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 */
});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*/ }
});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 */
});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 */
}
});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.
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
});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(){
}
}
}
});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.
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 | Key | Name |
|---|---|---|---|
ar |
Arabic | az |
Azerbaijani |
bg-BG |
Bulgarian | pt-BR |
Portuguese - Brasil |
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 | 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.