Bootbox.js is a small JavaScript library which allows you to create programmatic dialog boxes using Bootstrap modals, without having to worry about creating, managing or removing any of the required DOM elements or JS event handlers. Here’s the simplest possible example:
Compare that to the code you’d have to write without Bootbox:
Bootbox was originally created in 2011 with the sole purpose of wrapping JavaScript’s low level dialog methods with Bootstrap’s high level modal functionality. As such it is a small library focussed on providing basic programmatic dialogs with minimal fuss and overhead.
Bootbox is authored and maintained by Nick Payne (@makeusabrew). Thanks are also due to the contributors!
The library exposes three methods designed to mimic their native JavaScript equivalents. Their exact method signatures are flexible as each can take various parameters to customise labels and specify defaults, but they are most commonly called like so:
The only required argument is message, although you’re unlikely to want to ever call confirm or prompt without a callback argument otherwise you’ll have no way of determining what the user’s response was. Even when calling alert a callback is useful to determine when the user dismissed the dialog since our wrapper methods can’t & don’t block like their native counterparts: they are asynchronous rather than synchronous.
Each of these three methods calls a fourth public method which you too can use to create your own custom dialogs:
Please note: the ‘Example’ object used in the following examples simply displays a notification to help illustrate when each callback is invoked. It is nothing to do with Bootbox itself, but you may view its source if you’re interested in how it works.
The latest stable version of Bootbox is 3.3.0. You can download the minified library bootbox.min.js for use in production, or the uncompressed bootbox.js for use in development. I wouldn’t recommend hotlinking to either file as Github does not serve the correct mime type which may cause security warnings to be triggered based on your browser’s settings.
If you wish you may also see a full list of releases or download the latest copy of the entire repository (including build files and tests) in zip or tarball format. Realistically the only reason you should be using anything other than the 3.x.x series is if you are restricted by the version of Bootstrap you’re using—see the following section for full details.
All versions of Bootbox stand on the shoulders of two great giants: Bootstrap and jQuery. The exact version of Bootstrap depends on the version of Bootbox you’re using. This has become slightly more complex than I’d like but hopefully this handy table will clear things up (if it doesn’t then please tell me!):
Bootbox version | Min. Bootstrap version | Max. Bootstrap version | Notes |
---|---|---|---|
4.x.x | 3.0.0 (probably) | - | Neither of these versions exist, but this is the rough plan… |
3.x.x Latest | 2.2.2 | 2.3.2 | Current release. Anything > Bootstrap 2.3.2 is untested |
2.x.x | 2.0.0 | 2.0.4 | As you can see, Bootstrap 2.1.x was never officially supported |
1.x.x | 1.3.0 | 1.4.0 | Don’t download this version of Bootbox—it’s old |
All versions of the library require at least jQuery 1.7.1, though 1.8.3 or above is recommended for the 3.x.x releases.
Once you’ve got your dependencies sorted, usage is fairly straightforward and much like any other JavaScript library you’ve ever used. The library creates a single global instance of a bootbox object:
When you’re up and running check out some examples or the documentation.
Bootbox is a free, open source project. As such you can help out in a number of ways from simply raising an issue to forking the project and submitting a pull request.
I’m particularly keen to improve the examples and make a proper start on the API docs, so pull requests contributing towards the gh-pages branch (which you’re looking at!) are extremely welcome.
Lastly—please just help spread the word!