Bootbox.js - alert, confirm and flexible dialogs for twitter's bootstrap framework

UPDATE 01/02/2012: Version 2.0.0 of the Bootbox library is out. Whilst this tutorial is still largely accurate and version 1.1.2 will work with the 1.x series of Twitter's Bootstrap framework, you should check out the updated version here.

This article discusses a GitHub repository – feel free to browse the code or follow the project.

I’ve been using twitter's bootstrap framework for a number of site builds recently, mainly because it gets me from black-and-white markup to vaguely-presentable websites in a very small amount of time. Version 1.3 introduced some JavaScript plugins to complement the array of stylistic elements it already provided - notably code to invoke dialog boxes, or modals. A recent project I've been working on required extensive use of JavaScript's native alert and confirm dialogs, but their crude behaviour and wildly varying appearance between browsers is always somewhat dissatisfying, so I wanted combine their basic functionality with bootstrap's slick looking dialog boxes. Enter bootbox.js - alert() and confirm() like behaviour using twitter's modal dialog boxes.

Dialogs using Twitter Bootstrap

You may be wondering why a few wrapper methods around bootstrap's built-in dialog capabilities are either necessary or desirable. To begin to answer that, let's look at the code required to show a simple alert style dialog programatically using bootstrap:

Note that this example is purely for demonstration purposes - you probably don't want to show an obtrusive dialog as soon as the page loads! Nevertheless, as you can see from the previous snippet, we have to:

  1. Create the dialog's HTML and have it present somewhere in the DOM
  2. Add the buttons to dismiss the dialog
  3. Wire up the JavaScript handlers for each button present in the dialog
  4. Ensure the handlers are unbound when the dialog is hidden
  5. Show and hide the dialog itself

It's important to stress that none of these points are negative, nor are they particularly arduous. However, when you want lots of dialogs and you don't want to create all of the HTML and JavaScript for each one, it can get a bit unwieldy. This is where bootbox comes in.

Bootbox.js Alerts

Let's dive straight in and see the most simple example of a bootbox alert in action:

Which results in the following dialog:

So far, so simple - you've got the same result for a fraction of the code. Additionally, bootbox tries to mimic the behaviour of JavaScript's built-in alert as best as possible, hence the 'OK' button is automatically focused so the user can dismiss it by hitting the return key. This brief example demonstrates how bootbox simplifies creating, showing and dismissing bootstrap's dialogs, so let's now go on and look at what else it can do.

Alert Callbacks

The typical use case for an alert dialog is to present the user with a blocking notification which they have to acknowledge before continuing - crucially in JavaScript this translates into literally blocking the script's execution when using alert or confirm, meaning that as a developer you can guarantee that the alert has been dismissed before subsequent code executes. In userland, you can’t block the script's thread of execution, so we have to resort to a familiar ally if we want to delay execution of some code until we're sure a user has processed our notification. This ally comes in the form of a callback function provided as an argument to our bootbox alert method. Let’s take a look at an example:

This means the bootbox API isn’t like-for-like with the native JavaScript methods it mimics, but it's a suitable alternative and one which provides a very familiar interface to JavaScript developers. Besides, the way the native methods block everything isn't particularly pleasant anyway.

Custom button labels

Last but not least on the subject of alert boxes, you can provide a custom label if you’re not happy with the standard ’OK’ button:

Resulting in the following button being displayed:

As you can see, the argument list is flexible - the general rule of thumb is that a callback method, if provided, should always be the last argument.

Confirm dialogs

The native confirm method is as useful — and in some cases certainly more useful — than the alert method, as it not only alerts the user but prompts them to make a meaningful decision which will impact subsequent program flow based on their choice. Let's take a look at its most basic usage:

A confirm without a callback isn't particularly useful, but since it’s entirely possible using the native method, it’s possible with bootbox.

Confirm callbacks

Let’s look at getting the most out of of the choices we offer the user. The callback we provide will be populated with a boolean representing which choice the user made as per the native method:

The API provided follows the same format of bootbox.alert, which means we can override one or both of the button labels we show the user if we want to:

Custom dialogs

Under the hood, bootbox.alert and bootbox.confirm just process the arguments provided to them and ship them off to bootbox.dialog which is a public method which you can call too. It takes a range of flexible arguments which allow the creation of complex dialogs with a variety of buttons and callbacks. Of course, you can create very simple dialogs too, and although you’re probably better off using bootbox.alert to do so let’s take a look at the most simple dialog we can create:

The above snippet isn't very useful since it provides no buttons, meaning the user can't actually respond to the dialog at all. Let's sort that out, and while we're at it, let's add a callback function (though the callback key is entirely optional):

For convenience, the following form is equivalent if you want to provide a label and a callback without a custom button class:

What's this about button classes? So far we haven't provided any at all, which causes bootbox to do some head scratching to work out the most appropriate classes to apply to each button (e.g. primary on a single button, danger and primary for two buttons). We can provide a class key to customise the appearance of our button labels as per the classes provided by twitter's bootstrap framework:

Multiple buttons

So far, we've only looked at a custom dialog with one button displayed to the user. However, if you're using bootbox.dialog in the first place, you probably want more than this. Let's have a look at a significantly more complex dialog:

Please note the subtle difference in the method's arguments - the second of which is now an array of objects, rather than just a single button declaration.

Other options

We can specify a third argument to the dialog method which closely resembles the options accepted by bootstrap's $.modal method:

In fact, the only difference is that you can provide an onEscape option, which is a callback to be executed when the user dismisses the dialog with the escape key:

Internally, the onEscape option is used when calling bootbox.alert meaning that a user can dismiss an alert message by pressing escape. Since confirm dialogs require a decision, the escape key is disabled when calling bootbox.confirm. Of course, with bootbox.dialog you can use onEscape however you wish - you can disable it, you can pass it the same callback as one you provide to one of its buttons, or you can give it an entirely customised callback. The choice is yours.

Hiding dialogs

By and large, you'll want your user to determine when it's time to hide a dialog by choosing one of its options. However, there may be times when you need to programatically do this. So far we haven't been interested in the return values of any of the bootbox methods, which is always the DOM element created representing the modal dialog box. If you assign this return value to a variable then you can hide it using twitter's $.modal('hide') method:

An alternative use case is when you want to hide all active instances of bootbox dialogs. Although you shouldn't really have more than one dialog on screen at once, if you do (or if you don't want to keep track of your dialogs using variables), then bootbox has a convenience method to hide all of its dialogs at once:

One final note on hiding dialogs in this manner - please note that none of your callbacks, either assigned to a button selection or the escape key, will be triggered when dialogs are programatically hidden.

Bootbox requirements

Bootbox naturally requires on twitter's bootstrap CSS, and the modals require the bootstrap-modal.js JavaScript too. Additionally, since Twitter's Bootstrap JavaScript plugins require jQuery or Ender, so does bootbox (to be honest, it has only been tested thus far with jQuery).

Final thoughts

Bootbox wasn't really designed as a plugin per-se, but as it evolved it felt like it was worth polishing off and releasing stand alone. The source code is naturally available on GitHub. A very simple demo page is available in the repository based largely on the example gists embedded throughout this article, though it could certainly do with a bit of attention. Any bugs, features or pull requests are of course most welcome. If you enjoyed this article, why not watch the project or follow me for updates about it, or spread the word using the tweet button below. Thank you!

Related Articles

Comments

Ian
Looks great, could be a real time-saver!
Túbal Martín
Good job guys!! I'll use it in my next project. BTW, Have you submitted it to Bootstrap creators? they may like it ;)
Nick
@Túbal - no, not yet, but a few people have suggested I do so. I'll send them a tweet or two - and thanks for the feedback!
Kevin Bond
Very nice, what about an input prompt dialogue (to replace js native one)?
Nick
@Kevin - I thought about it after writing this article, as it would be nice to 'complete the set' so to speak. I'll have a think about how and where it fits, so yes, it'll probably be added shortly :)
Kevin John Ventura
Hi. I'm having problems on IE. Any ideas about it. The alert doesn't appear to me in IE. Thanks! ;)
Felix
Thanks a lot, I was just trying to fight with bootstrap's modal stuff. This is saving me a lot of time <3
Nick
Hi folks - the IE issues should now be resolved (only tested in IE8, others welcome).
Kevin John Ventura
Hi Nick! Thanks for the quick fix! Keep Rocking!
mrchess
Cool! IMO the Confirm Dialog cancel should be the regular grey. Two call-to-action buttons can be confusing.
Nick
@mrchess - interestingly someone else brought the same thing up on github. I wasn't convinced but now I'm thinking twice about it!
Phillip Cohen
Yeah, "OK" can stand out, but"cancel" should definitely be neutral.
Nick
@Phillip - cancel is now neutral as of v1.1.0 after some persuasive arguments over on Github :)
Júnior Messias
Add locale Brazil...
br:{OK:"OK",CANCEL:"Cancelar",CONFIRM:"Sim"}
mike
This bootbox rocks. I truly like it and thanks alot.
Philip Senechal
Awesome plugin, love it! Is there a simple way with the Confirm dialog to allow the href action of the <a> tag when the modal is confirmed and prevent it when the modal is not confirmed? Thanks!
Nick
@philip: something like this I suspect (untested!) https://gist.github.com/1709535
Philip Senechal
Thanks Nick...I figured it out actually. e.target has the original href. I'm using it with an MVC ActionLink similar to this: https://gist.github.com/1711511
Nick
Ah of course - e.target is a bit neater. Glad you got it sorted :)

Comments are now closed.