Bootbox API

Currently viewing documentation for version 4.x. Documentation is also available for v3.x and v2.x.

bootbox.alert(…)

A simple alert dialog with a single button. Pressing the ESC key or clicking the close button dismisses the dialog. If a callback is provided it is not passed any value when executed.

Usage

Default

This is the simplest usage of bootbox, requiring only the text of the message you wish to show:

bootbox.alert("Your message here…")

Default, with callback

All Bootbox dialogs, unlike native alerts, confirms, or prompts, are non-blocking events. As such, if you need to have code execute only upon dismissal of the dialog, you should supply a callback function:

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

Alert options

Alerts can be customized, using the options descibed below.

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

bootbox.confirm(…)

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.

Usage

Default, with callback

This version 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("Your message here…", function(result){ /* your callback code */ })

Confirm options

Confirm dialogs can be customized, using the options descibed below.

bootbox.confirm({ 
    size: 'small',
    message: "Your message here…", 
    callback: function(result){ /* your callback code */ }
})

bootbox.prompt(…)

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.

Usage

Default, with callback

This version 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 canceled or dismissed the dialog; otherwise it is passed the value of the text input.

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

Prompt options

Prompt dialogs can be customized, using the options descibed below.

bootbox.prompt({ 
    size: 'small',
    message: "Your message here…", 
    callback: function(result){ /* your callback code */ }
})

bootbox.dialog(…)

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 following snippet attempts to demonstrate these options as best as possible, though more formal documentation would be welcome:

Options can be passed in as a JavaScript object. Please note that not all options are valid for all dialog types.

Name Type Description

message

Required
String | Element

Text (or markup) displayed in the dialog.

title String | Element

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

locale String

The locale settings 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

callback

Required *
Function

* Alerts do not require a callback.

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

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

Required
Object

Buttons are defined as JavaScript objects. The minium required to define a button is:

buttonName: {
    label: 'Your Label Text',
    callback: function() {
    }
}

Defaults:

alert "ok"
confirm "cancel", "confirm"
prompt "cancel", "confirm"

bootbox.init(function)

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

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.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.setLocale(String name)

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

bootbox.hideAll()

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

dialog.modal('hide')
© 2011-2015 Nick Payne. I run a small company—why not see if you want to work with us?