FAQ / Troubleshooting

Bootbox.js is designed to be relatively easy to use, but there are some known issues and frequently asked questions, as noted here.

Q1: Native dialogs block the execution thread. Why doesn't Bootbox?

A: The simplest answer is: because Bootstrap modals don't.

Bootbox is primarily an engine for generating markup on which Bootstrap's modal() function can be called. Keep this is mind: Bootstrap modals are really just positioned <div> elements.

Additionally, the modal() function is an asynchronous function, since JavaScript didn't really provide wait until this thing is done functionality in versions prior to ES7 (with async/await). Since Bootstrap 4 is still offering some support for Internet Explorer (which only supports ES6 and lower), modal() doesn't use async/await (nor does Bootbox).

There is an experimental element, <dialog> (MDN), which (in theory) will be able to thread-block; it's basically a standardized version of an interactive modal element which can be styled. Browser support isn't really where it needs to be in order to make the switch, so for now, remember to use callbacks with your modals.

Q2: How do I keep my page from submitting when I use bootbox.confirm()?

A: See Native dialogs block the execution thread. Why doesn't Bootbox?

To reiterate, Bootbox modals are just positioned <div> elements. The modals are shown and hidden using asynchronous JavaScript functions, so (unlike the native confirm() function) the thread of your code is not blocked when you call bootbox.confirm(). To get around this, Bootbox uses the callback pattern with our alert, confirm, and prompt functions. To respond to a user's input, you can either define an inline callback function, like so… 

bootbox.confirm({
    message: "Are you sure?",
    callback: function(result){ 
        /* result = true if OK clicked, false otherwise  */
    }
});

…or pass a reference to an external function: 

bootbox.confirm({
    message: "Are you sure?",
    callback: handleConfirm
});

function handleConfirm(result){ 
    /* result = true if OK clicked, false otherwise */
}

Any process which depends on your user's response must be placed in the callback. If you're handling something like the onSubmit event of a <form>, you'll need to cancel the event in order to prevent the event from proceeding: 

let form = $('form');
form.on('submit', function(e) {
    bootbox.confirm({
        message: "Are you sure?",
        callback: handleConfirm
    });

    // Or use e.preventDefault();
    return false; // prevents form submission
});

function handleConfirm(result){ 
    /* result = true if OK clicked, false otherwise 
}

The same advice applies to bootbox.alert() and bootbox.prompt().

Q3: How do I require a non-empty value when I use bootbox.prompt()?

A: To require a value to be entered / selected, set the required option to true. This will tell Bootbox to add the required property to the generated form control, and to trigger the browser's built-in validation when the dialog is submitted. 

bootbox.prompt({ 
    required: true,
    title: 'What is your name?',
    callback: function(result){ 
        /* result = String containing user input if OK clicked or null if close button clicked */ 
    }
});
Example bb.3
What is your name?

Q4: I don't see my native language as a locale option. Why not? How do I add it?

A: Most localizations have been submitted by the community. If you don't see the locale you're looking for, then it likely hasn't been submitted yet.

To add a new locale:

  1. Fork the Bootbox repository.
  2. Navigate to the /locales/ directory.
  3. Within the /locales/ directory, create a new JavaScript file named with the IANA code for your language (e.g. 'en-US', 'pt-BR').
  4. Copy the template, below, into your new file. Values denoted with brackets (i.e. {{IANA code}}) represent the values you will fill in for this locale. 
// locale : {{name of locale / language}}
// author : {{your name (optional)}}
bootbox.addLocale('{{IANA code}}', {
  OK      : '{{OK text}}',
  CANCEL  : '{{Cancel text}}',
  CONFIRM : '{{Confirm text}}'
});

Add a unit test for your new locale. Locales without tests are rarely pulled in. To add your test:

  1. Navigate to the /tests/ directory.
  2. Within the /tests/ directory, locate the JavaScript file named locales.test.js.
  3. Just before the closing });, copy the following template, inserting the correct values for your locale: 
describe('{{locale name}}', function() {
  beforeEach(function() {
    return this.setLocale('{{IANA code}}');
  });
  it('shows the correct OK translation', function() {
    return expect(this.labels.ok).to.equal('{{OK text}}');
  });
  it('shows the correct CANCEL translation', function() {
    return expect(this.labels.cancel).to.equal('{{Cancel text}}');
  });
  return it('shows the correct CONFIRM translation', function() {
    return expect(this.labels.confirm).to.equal('{{Confirm text}}');
  });
});

Run grunt. This will regenerate the bootbox.locales.js and bootbox.all.js files and run the test suite. If all tests pass, submit a pull-request; please include a meaningful commit message.

Q5: When I use Bootbox, the header's all messed up. What gives?

A: Bootbox 6 is intended to work with any currently-supported version of Bootstrap — meaning you can use it with Bootstrap 3.4.1 and newer. If you're seeing something similar to this… 

bootbox.alert({ 
    title: 'My title',
    message: "Your message here…" 
});
Example bb.4

My title

Your message here…

… then you're probably using Bootstrap 4 or newer and Bootbox 4. The markup structure and CSS rules for Bootstrap 4+ are not compatible with the markup used in Bootstrap 3 modals, which is what Bootbox 4 generates. At the moment, there are no plans to update Bootbox 4, so please upgrade to Bootbox 5 or newer if you are able.

Q6: Help! My package manager is telling me that Bootbox is insecure!

A: That's… unfortunate.

We're aware of at least one notice (via a HackerOne issue) on the npm package. Here's the gist: we use jQuery's .html() as part of the construction of our modals. Because that process (in part) includes the values passed in via the title and message options, there's a possible XSS vector there, as we do not sanitize the content you pass in for those options. That's how Bootbox has always worked, and it's how we allow formatted messages in our dialogs, and is a key part of the custom dialog function.

Sanitizing HTML properly is not a trivial enterprise. It's also out of scope for Bootbox. If you're using a UI framework, it probably has a pretty good sanitizer tool built in. If not, there are a lot of existing libraries that you can pipeline into the process of using Bootbox.

In summary: if you're using user-submitted content, sanitize that content before passing it to Bootbox.