# Carousel carousel.js

A slideshow component for cycling through elements, like a carousel. Nested carousels are not supported.

## Examples

Previous Next
{% highlight html %}

...
...
...
Previous Next
{% endhighlight %}

#### Accessibility issue

The carousel component is generally not compliant with accessibility standards. If you need to be compliant, please consider other options for presenting your content.

#### Transition animations not supported in Internet Explorer 8 & 9

Bootstrap exclusively uses CSS3 for its animations, but Internet Explorer 8 & 9 don't support the necessary CSS properties. Thus, there are no slide transition animations when using these browsers. We have intentionally decided not to include jQuery-based fallbacks for the transitions.

#### Initial active element required

The `.active` class needs to be added to one of the slides. Otherwise, the carousel will not be visible.

#### Glyphicon icons not necessary

The `.glyphicon .glyphicon-chevron-left` and `.glyphicon .glyphicon-chevron-right` classes are not necessarily needed for the controls. Bootstrap provides `.icon-prev` and `.icon-next` as plain unicode alternatives.

### Optional captions

Add captions to your slides easily with the `.carousel-caption` element within any `.item`. Place just about any optional HTML within there and it will be automatically aligned and formatted.

### First slide label

Nulla vitae elit libero, a pharetra augue mollis interdum.

### Second slide label

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

### Third slide label

Praesent commodo cursus magna, vel scelerisque nisl consectetur.

Previous Next
{% highlight html %}

### ...

...

{% endhighlight %}

## Usage

### Multiple carousels

Carousels require the use of an `id` on the outermost container (the `.carousel`) for carousel controls to function properly. When adding multiple carousels, or when changing a carousel's `id`, be sure to update the relevant controls.

### Via data attributes

Use data attributes to easily control the position of the carousel. `data-slide` accepts the keywords `prev` or `next`, which alters the slide position relative to its current position. Alternatively, use `data-slide-to` to pass a raw slide index to the carousel `data-slide-to="2"`, which shifts the slide position to a particular index beginning with `0`.

The `data-ride="carousel"` attribute is used to mark a carousel as animating starting at page load. It cannot be used in combination with (redundant and unnecessary) explicit JavaScript initialization of the same carousel.

### Via JavaScript

Call carousel manually with:

{% highlight js %} $('.carousel').carousel() {% endhighlight %}

### Options

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

Name | type | default | description
--- | --- | --- | ---
interval | number | 5000 | The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.
pause | string | null | "hover" | If set to `"hover"`, pauses the cycling of the carousel on `mouseenter` and resumes the cycling of the carousel on `mouseleave`. If set to `null`, hovering over the carousel won't pause it.
wrap | boolean | true | Whether the carousel should cycle continuously or have hard stops.
keyboard | boolean | true | Whether the carousel should react to keyboard events.

### Methods

#### `.carousel(options)`

Initializes the carousel with an optional options `object` and starts cycling through items.

{% highlight js %} $('.carousel').carousel({ interval: 2000 }) {% endhighlight %}

#### `.carousel('cycle')`

Cycles through the carousel items from left to right.

#### `.carousel('pause')`

Stops the carousel from cycling through items.

#### `.carousel(number)`

Cycles the carousel to a particular frame (0 based, similar to an array).

#### `.carousel('prev')`

Cycles to the previous item.

#### `.carousel('next')`

Cycles to the next item.

### Events

Bootstrap's carousel class exposes two events for hooking into carousel functionality.

Both events have the following additional properties:

- `direction`: The direction in which the carousel is sliding (either `"left"` or `"right"`).
- `relatedTarget`: The DOM element that is being slid into place as the active item.

All carousel events are fired at the carousel itself (i.e. at the `<div class="carousel">`).

Event Type | Description
--- | ---
slide.bs.carousel | This event fires immediately when the `slide` instance method is invoked.
slid.bs.carousel | This event is fired when the carousel has completed its slide transition.

{% highlight js %} $('#myCarousel').on('slide.bs.carousel', function () { // do something… }) {% endhighlight %}