# Carousel carousel.js

## Examples

The slideshow below shows a generic plugin and component for cycling through elements like a carousel.

{% highlight html %}

...
...
...
{% endhighlight %}

#### 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.

### 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.

{% highlight html %}

### ...

...

{% 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.

## 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.

### 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 | "hover" | Pauses the cycling of the carousel on mouseenter and resumes the cycling of the carousel on mouseleave.
wrap | boolean | true | Whether the carousel should cycle continuously or have hard stops.

### 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.

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 %}