Documentation
Currently viewing documentation for version 5.x.
Currently viewing documentation for version 5.x.
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.
This is the simplest usage of Bootbox, requiring only the text of the message you wish to show.
bootbox.alert("Your message here…")
Your message can also contain HTML.
bootbox.alert("Your message <b>here…</b>")
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 */ }
})
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.
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 */ })
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.
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.
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.
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 */ })
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.
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.
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 dialogs are (by default) single-line text inputs. You can modify the type of prompt Bootbox generates using the prompt-only options below.
Name | Type | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
value | String | Number | Array |
You can set the initial value of the prompt using the
To pre-select more than one value (when using the checkbox type), use an array for the |
||||||||||||||||||||||||
inputType |
String |
Changes the type of input generated for the prompt dialog. Valid values, with their class selectors:
Additionally, checkbox and radiobuttons are wrapped in a parent element,
Date input type and browser support
At the time this is written, every major browser which supports the YYYY = four-digit year MM = two-digit month (01=January, etc.) DD = two-digit day of month (01 through 31) |
||||||||||||||||||||||||
inputOptions | Array |
If you specify
|
||||||||||||||||||||||||
min, max | String | Number | Date string | Time string |
The
For
For
For |
||||||||||||||||||||||||
step | String | Number |
The
Can be the string value
Warning: For most browsers, date inputs are buggy in their implementation of See the MDN article for more information. |
||||||||||||||||||||||||
maxlength | Number |
Set the
Valid for
Default: |
||||||||||||||||||||||||
pattern | String |
Set the
Can be added for any input type, but generally only used for
Default: |
||||||||||||||||||||||||
placeholder | String |
Set the
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 either has focus (depending on
the browser) or has a value. Use the
Valid for
If specified for
Default: |
||||||||||||||||||||||||
required | Boolean |
Set the
Valid for
Default: |
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.
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>'
})
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(){
}
}
}
})
Please see the Examples page for more examples of custom dialogs.
Bootbox dialogs can be configured using the options below.
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
message | String | Element |
Text (or markup) displayed in the dialog. Required for alert, confirm, and custom dialogs |
||||||
title | String | Element |
Adds a header to the dialog and places this text (or markup) in an Required for prompt |
||||||
callback | 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:
Confirm and prompt callbacks must supply an argument for the result; for confirm,
it will be a
or
For any callback, if you do not want the dialog to close when the callback completes, add
Default: |
||||||
onEscape | Boolean | Function |
Allows the user to dismiss the dialog by hitting ESC, which will invoke this function. Options:
Default: |
||||||
show | Boolean |
Whether the dialog should be shown immediately. Default: |
||||||
backdrop | Boolean |
Whether the dialog should be have a backdrop or not. Also determines whether clicking on the backdrop dismisses the modal. Options:
Default:
* When this value is set to |
||||||
closeButton | Boolean |
Whether the dialog should have a close button () or not. Default: |
||||||
animate | Boolean |
Animate the dialog in and out (requires a browser which supports CSS animations). Default: |
||||||
className | String |
An additional class to apply to the dialog wrapper. Default: |
||||||
size | String |
Adds the relevant Bootstrap modal size class to the dialog wrapper. Valid values are
Requires Bootstrap 3.1.0 or newer. Default: |
||||||
locale | 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. |
||||||
Object |
Buttons are defined as JavaScript objects. The minimum shortform requirement to define a button is:
The complete definition of a button object is:
Options:
Each of the available button options can be overridden to use custom content (text or HTML) and CSS styles. For example:
You cannot override the callbacks for the alert, confirm, and prompt dialog's buttons. |
|||||||
swapButtonOrder | Boolean |
Flips the order in which the buttons are rendered, from cancel/confirm to confirm/cancel. Default: |
||||||
centerVertical | Boolean |
If Requires Bootstrap 4.1.0 or newer. Default: |
The following locales are available:
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 | th |
Thai |
tr |
Turkish | uk |
Ukrainian |
zh_CN |
Chinese (People's Republic of China) | zh_TW |
Chinese (Taiwan / Republic of China) |
To use any locale other than en, you must do one of the following:
bootbox.all.js
or bootbox.all.min.js
file, which includes all locales.
bootbox.locales.js
or bootbox.locales.min.js
after bootbox.js
.
fr.js
to use the French locale, for example), found in the src/locales
directory.
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.
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.
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:
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
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 : ''
}
Allows the user to remove a locale from the available locale settings.
Allows the user to get a locale object from the available locale settings. If name
is empty,
all locales will be returned.
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.
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.
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.
The value(s) returned by a Bootbox prompt are not sanitized in any way.