Documentation

Currently viewing documentation for version 4.x.

Other versions available: v3.xv2.x.

Bootbox is proudly sponsored by Finch. Test local websites across multiple devices, share them with your team and get feedback from clients through a secure, public URL.
meetfinch.com

Please note:

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 can also contain HTML.

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

Advanced Usage

All Bootstrap modals, unlike native alerts, confirms, or prompts, generate non-blocking events. Because of this limitation, code that should not be evaluated until your user has dismissed your alert should be placed (or called) within a callback function:

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

Alerts can be customized, using the options described below.

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

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

Please note:

All Bootstrap modals, unlike native alerts, confirms, or prompts, generate non-blocking events. 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.

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

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

Please note:

All Bootstrap modals, unlike native alerts, confirms, or prompts, generate non-blocking events. 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.

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

Please note:

Prompt requires the title option (when using the options object) and disallows the message option.

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.

Name Description
value

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

inputType

Changes the type of input generated for the prompt dialog. Valid values for inputType are:

text (default), textarea, email, select, checkbox, date, time, number, and password.

inputOptions

If you specify select or checkbox 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.

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>' })
Example bb.8

Advanced Usage

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 <h4> element.

Required for prompts

callback

Function

Required for confirm and prompt

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

Default: null

onEscape 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 Boolean

Whether the dialog should be shown immediately.

Default: true

backdrop 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 Boolean

Whether the dialog should have a close button or not.

Default: true

animate Boolean

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

Default: true

className String

An additional class to apply to the dialog wrapper.

Default: null

size String

Adds the relevant Bootstrap modal size class to the dialog wrapper. Valid values are 'large' and 'small'

Requires Bootstrap 3.1.0 or newer.

Default: null

buttons

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.

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

Currently available:

  • bg_BG
  • br
  • cs
  • da
  • de
  • el
  • en
  • es
  • et
  • fa
  • fi
  • fr
  • he
  • hu
  • hr
  • id
  • it
  • ja
  • lt
  • lv
  • nl
  • no
  • pl
  • pt
  • ru
  • sq
  • sv
  • th
  • tr
  • zh_CN
  • zh_TW

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.hideAll()

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

dialog.modal('hide')

Using Bootbox does have some caveats, as noted below.

Dialog code does not block code execution

All Bootstrap modals, unlike native alerts, confirms, or prompts, generate non-blocking events. Because of this limitation, code that should not be evaluated until a user has dismissed your dialog should be placed (or 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.