Twitter Bootstrap 101: The Carousel

One of Twitter Bootstrap’s many handy features is a pleasing sliding carousel for featuring images and content! Setup is not difficult. It requires some structured markup, the Bootstrap jQuery plugin, and a couple of lines of JavaScript to initialize it. Let me show you how it’s done!

The Screencast

For those of you who appreciate tutorials in black and white, let’s go over:

1. The Carousel Markup
2. The Carousel JavaScript
3. Adjusting Carousel Settings
4. Supplying your own Content and Captions

Step 1: The Carousel Markup

The Bootstrap carousel requires a specific markup pattern, with appropriate classes.

Carousel and Carousel-inner

<!--  Carousel - consult the Twitter Bootstrap docs at
      http://twitter.github.com/bootstrap/javascript.html#carousel -->
<div id="this-carousel-id" class="carousel slide"><!-- class of slide for animation -->
  <div class="carousel-inner">
    <div class="item active"><!-- class of active since it's the first item -->
      <img src="http://placehold.it/1200x480" alt="" />
      <div class="carousel-caption">
        <p>Caption text here</p>
      </div>
    </div>
    <div class="item">
      <img src="http://placehold.it/1200x480" alt="" />
      <div class="carousel-caption">
        <p>Caption text here</p>
      </div>
    </div>
    <div class="item">
      <img src="http://placehold.it/1200x480" alt="" />
      <div class="carousel-caption">
        <p>Caption text here</p>
      </div>
    </div>
    <div class="item">
      <img src="http://placehold.it/1200x480" alt="" />
      <div class="carousel-caption">
        <p>Caption text here</p>
      </div>
    </div>
  </div><!-- /.carousel-inner -->
  <!--  Next and Previous controls below
        href values must reference the id for this carousel -->
    <a class="carousel-control left" href="#this-carousel-id" data-slide="prev">&lsaquo;</a>
    <a class="carousel-control right" href="#this-carousel-id" data-slide="next">&rsaquo;</a>
</div><!-- /.carousel -->

Once we’ve supplied the markup, we need to initialize the carousel JavaScript to do its work on this carousel.

Step 2: The Carousel JavaScript

Let’s begin by making sure the necessary JavaScript is connected to this page. You’ll find your JavaScript links near the bottom of the page, near the closing body tag.

jQuery

The best, most highly recommended way to link jQuery is to link to a CDN-hosted version. This provides a speedier download, and it may already be cached in your user’s browser.

But of course it would be nice to have a fallback, so that if something happens to that CDN-hosted version, the user can get it locally from your own site files. That is exactly what the good folks at the HTML5 Boilerplate recommend, and it looks like this:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script>window.jQuery || document.write('<script src="js/jquery-1.7.2.min.js"><\/script>')</script>

Note that the first line reaches out to Google’s hosted version. The second line uses JavaScript to check that the first line did its job. If not, it auto-generates a link to your own hosted copy of jQuery, which you’ve included in your own site files (as I have here).

Bootstrap’s jQuery Plugins

Once we’ve linked jQuery, we need Bootstrap’s jQuery plugins. I’ve included the complete compiled and minified version of all of Bootstrap’s plugins. Thus my link looks like this:

<script src="js/bootstrap.min.js"></script>

Initialize the Carousel

Once we’ve provided jQuery plus Bootstrap’s plugins, we just need to initialize the Carousel plugin to do its work on our carousel.

<script>
  $(document).ready(function(){
    $('.carousel').carousel();
  });
</script>

In plain English, this means: Once the HTML document is ready, identify the element(s) with a class of "carousel", and direct the carousel plugin to do its thing to it.

Refresh and Check

Once the markup is in place, and the JavaScript has been supplied correctly, you should be able to refresh your browser and see the results. Each image rotation takes five seconds. Be sure that your mouse does not hover over the slideshow, as this pauses its timer.

Step 3: Adjust Settings as Desired

You can add parameters to adjust the time between the carousel sliding behavior.

For example, you could change the timing to 2-second (2,000 millisecond) intervals as follows:

<script>
  $(document).ready(function(){
    $('.carousel').carousel({
      interval: 2000
    });
  });
</script>

Step 4: Your Own Content and Captions

In the markup for Step 1, above, I’ve used Placehold.it images. Note that images of 1200 pixels wide are large enough to stretch the full maximum width of the standard Bootstrap responsive site. I’ve used a ratio of 1200x480px simply because it seems visually pleasing to me — at least on my large monitor!

At this point you are free to:

1. Select your desired images (the carousel can handle as many as you’d like).
2. Edit them to your desired dimensions (keeping them consistent).
3. Wrap the images in links if you’d like (as I have done in the demo).
4. Supply your desired captions.

The Results

Always remember, as you try things out and tweak them, Twitter Bootstrap’s excellent documentation is your friend. And if you can use additional help, a lot of folks find help in the Twitter Bootstrap Google Group.

Take a look at the final result.