JavaScript in Bootstrap

Individual or compiled

Data attributes

You can use all Bootstrap plugins purely through the markup API without writing a single line of JavaScript. This is Bootstrap's first class API and should be your first consideration when using a plugin.

That said, in some situations it may be desirable to turn this functionality off. Therefore, we also provide the ability to disable the data attribute API by unbinding all events on the body namespaced with `'data-api'`. This looks like this:

$('body').off('.data-api')

Alternatively, to target a specific plugin, just include the plugins name as a namespace along with the data-api namespace like this:

$('body').off('.alert.data-api')

Programmatic API

We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.

$(".btn.danger").button("toggle").addClass("fat")

All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):

Each plugin also exposes it's raw constructor on a `Constructor` property: $.fn.popover.Constructor. If you'd like to get a particular plugin instance, retrieve it directly from an element: $('[rel=popover]').data('popover').

Events

Bootstrap provides custom events for most plugin's unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. show) is triggered at the start of an event, and it's past participle form (ex. shown) is trigger on the completion of an action.

All infinitive events provide preventDefault functionality. This provides the abililty to stop the execution of an action before it starts.

Transitions bootstrap-transition.js

About transitions

For simple transition effects, include bootstrap-transition.js once alongside the other JS files. If you're using the compiled (or minified) bootstrap.js, there is no need to include this—it's already there.

Use cases

A few examples of the transition plugin:

Sliding or fading in modals

Fading out tabs

Fading out alerts

Sliding carousel panes

Modals bootstrap-modal.js

Examples

Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults.

Via JavaScript

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-backdrop="".

Name

type

default

description

backdrop

boolean

true

Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.

keyboard

boolean

true

Closes the modal when escape key is pressed

show

boolean

true

Shows the modal when initialized.

remote

path

false

If a remote url is provided, content will be loaded via jQuery's load method and injected into the .modal-body. If you're using the data api, you may alternatively use the href tag to specify the remote source. An example of this is shown below:

Via JavaScript

Options

None

Methods

$().dropdown()

A programatic api for activating menus for a given navbar or tabbed navigation.

ScrollSpy bootstrap-scrollspy.js

Example in navbar

The ScrollSpy plugin is for automatically updating nav targets based on scroll position. Scroll the area below the navbar and watch the active class change. The dropdown sub items will be highlighted as well.

Usage

Via data attributes

To easily add scrollspy behavior to your topbar navigation, just add data-spy="scroll" to the element you want to spy on (most typically this would be the body) and data-target=".navbar" to select which nav to use. You'll want to use scrollspy with a .nav component.

<body data-spy="scroll" data-target=".navbar">...</body>

Via JavaScript

Call the scrollspy via JavaScript:

$('#navbar').scrollspy()

Heads up!
Navbar links must have resolvable id targets. For example, a <a href="#home">home</a> must correspond to something in the dom like <div id="home"></div>.

Methods

.scrollspy('refresh')

When using scrollspy in conjunction with adding or removing of elements from the DOM, you'll need to call the refresh method like so:

Markup

You can activate a tab or pill navigation without writing any JavaScript by simply specifying data-toggle="tab" or data-toggle="pill" on an element. Adding the nav and nav-tabs classes to the tab ul will apply the Bootstrap tab styling.

Usage

Via data attributes

Just add data-toggle="collapse" and a data-target to element to automatically assign control of a collapsible element. The data-target attribute accepts a css selector to apply the collapse to. Be sure to add the class collapse to the collapsible element. If you'd like it to default open, add the additional class in.

To add accordion-like group management to a collapsible control, add the data attribute data-parent="#selector". Refer to the demo to see this in action.

Via JavaScript

Enable manually with:

$(".collapse").collapse()

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-parent="".

Name

type

default

description

parent

selector

false

If selector then all collapsible elements under the specified parent will be closed when this collapsible item is shown. (similar to traditional accordion behavior)

.carousel('prev')

.carousel('next')

Events

This event fires immediately when the slide instance method is invoked.

slid

This event is fired when the carousel has completed its slide transition.

Typeahead bootstrap-typeahead.js

Example

A basic, easily extended plugin for quickly creating elegant typeaheads with any form text input.

<input type="text" data-provide="typeahead">

Usage

Via data attributes

Add data attributes to register an element with typeahead functionality as shown in the example above.

Via JavaScript

Call the typeahead manually with:

$('.typeahead').typeahead()

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-source="".

Name

type

default

description

source

array, function

[ ]

The data source to query against. May be an array of strings or a function. The function is passed two arguments, the query value in the input field and the process callback. The function may be used synchronously by returning the data source directly or asynchronously via the process callback's single argument.

items

number

8

The max number of items to display in the dropdown.

minLength

number

1

The minimum character length needed before triggering autocomplete suggestions

matcher

function

case insensitive

The method used to determine if a query matches an item. Accepts a single argument, the item against which to test the query. Access the current query with this.query. Return a boolean true if query is a match.

sorter

function

exact match, case sensitive, case insensitive

Method used to sort autocomplete results. Accepts a single argument items and has the scope of the typeahead instance. Reference the current query with this.query.

highlighter

function

highlights all default matches

Method used to highlight autocomplete results. Accepts a single argument item and has the scope of the typeahead instance. Should return html.

Methods

.typeahead(options)

Initializes an input with a typeahead.

Affix bootstrap-affix.js

Example

The subnavigation on the left is a live demo of the affix plugin.

Usage

Via data attributes

To easily add affix behavior to any element, just add data-spy="affix" to the element you want to spy on. Then use offsets to define when to toggle the pinning of an element on and off.

<div data-spy="affix" data-offset-top="200">...</div>

Heads up!
You must manage the position of a pinned element and the behavior of its immediate parent. Position is controlled by affix, affix-top, and affix-bottom. Remember to check for a potentially collapsed parent when the affix kicks in as it's removing content from the normal flow of the page.

Via JavaScript

Call the affix plugin via JavaScript:

$('#navbar').affix()

Methods

.affix('refresh')

When using affix in conjunction with adding or removing of elements from the DOM, you'll want to call the refresh method:

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-offset-top="200".

Name

type

default

description

offset

number | function | object

10

Pixels to offset from screen when calculating position of scroll. If a single number is provide, the offset will be applied in both top and left directions. To listen for a single direction, or multiple unique offsets, just provided an object offset: { x: 10 }. Use a function when you need to dynamically provide an offset (useful for some responsive designs).