Fork me on GitHub

Carousel

Description

The carousel is an interaction that allows horizontal scrolling (with touch or buttons) between a set of items.

The CSS we need to use here is pretty picky, so make sure to check out the "required styles" below.

Attributes

Basic Advanced JavaScript
data-ur-set="carousel"
add this attribute to a div that wraps the whole interaction
data-ur-carousel-component="scroll_container"
for wrapping the whole scrolling container
data-ur-carousel-component="item"
wrap each scrollable item in this
data-ur-carousel-component="button"
for the previous and next buttons
data-ur-carousel-button-type="prev"/"next"
to distinguish the previous and next buttons

Required

data-ur-set="carousel"
  • this element should wrap the whole carousel.
  • multiple?: false
  • state: N/A
  • attributes (default settings are in italics)
    • optional: data-ur-touch: enabled/disabled
    • optional: data-ur-infinite: enabled/disabled (specify front to back wrapping behavior)
    • optional: data-ur-autoscroll: enabled/disabled (automatically scroll with interval)
    • optional: data-ur-autoscroll-delay: integer (autoscroll delay in milliseconds, default: 5000)
    • optional: data-ur-autoscroll-dir: next/prev (specify autoscroll direction)
    • optional: data-ur-transform3d: enabled/disabled (force use of translate3d on all devices)
    • optional: data-ur-fill: integer (force n carousel items to fit in container width, default: 0)
    • optional: data-ur-center: enabled/disabled (horizontally center current item)
data-ur-carousel-component="scroll_container"
  • this element should wrap the scrolling items on the carousel. This or the set needs position: relative.
  • multiple?: false
  • state: N/A
data-ur-carousel-component="item"
  • this attribute is for each item that needs to be displayed in the carousel
  • multiple?: true
  • state: active / inactive (reflects currently visible item)
  • must have float: left style

Optional

data-ur-carousel-component="button"
  • indicates the previous and next buttons
  • multiple?: true
  • state: enabled / disabled ("next" defaults to enabled / "prev" defaults to disabled)
  • attributes
    • required: data-ur-carousel-button-type: "next"/"prev" for the next and previous buttons, respectively
data-ur-carousel-component="count"
  • gives an indicator of the position of the carousel, in the form "1 of 8", etc.
  • multiple?: true
  • state: N/A
  • attributes
    • optional: data-ur-template: moustache template, e.g., "{{index}}/{{count}}"
data-ur-carousel-component="dots"
  • gives a container that changes data-ur-state on the corresponding child
  • multiple?: false
  • state: N/A

You can also directly initialize the widget in JavaScript (components can be passed in as strings/elements/arrays):

Uranium.lib.carousel({
  set: "#a",
  scroll_container: "#b",
  item: "#b > *"
},
{
  infinite: false // data-ur-* options
});

Instance

Access the widget via Uranium.carousel["DATA-UR-ID"]. The following methods are exposed for each widget:

update(options)
  • force the carousel to recalculate positioning
  • optional argument for updating certain options, e.g., {center: true, fill: 2}
jumpToIndex(index)
  • forces the carousel to jump to the specified (zero based) index
autoscrollStart()
  • start autoscroll
autoscrollStop()
  • stop autoscroll

Callbacks

load.ur.carousel
  • event triggered on the data-ur-set="carousel" node when all images have loaded
  • in upcoming versions of Uranium on jQuery, this event may be renamed "load" to match the naming convention of other events.
slidestart
  • event triggered on the data-ur-set="carousel" node when a transition from one thumbnail to the next starts
  • in some older versions of Uranium on jQuery, this event was named "slidestart.ur.carousel"
slideend
  • event triggered on the data-ur-set="carousel" node when a transition from one thumbnail to the next ends
  • in some older versions of Uranium on jQuery, this event was named "slideend.ur.carousel"

Demonstration

Example

Prev Next

1 2 3 4 5 6 7 8

The Code

    <div data-ur-set="carousel" data-ur-infinite="disabled">
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="prev">Prev</a>
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="next">Next</a>
      <span data-ur-carousel-component="count"></span>
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="1">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="2">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="3">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="4">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="5">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="6">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="7">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/200/200" alt="8">
      </div>
    </div>

Required Styles

[data-ur-set="carousel"] {
  overflow: hidden;
  position: relative;
}
[data-ur-carousel-component="scroll_container"] {
  clear: both;
  display: block;
}
[data-ur-carousel-component="scroll_container"]:after {
  clear: both;
  content: "";
  display: table;
}
[data-ur-carousel-component="scroll_container"] img {
  -webkit-user-drag: none;
}
[data-ur-carousel-component="item"] {
  display: inline-block;
  float: left;
}

Carousel Examples

Carousel inside Toggler

Carousels inside disabled content (display: none) aren't able to calculate their widths so alternate CSS is used here.

Example The Code CSS
Show/Hide Carousel
1 2 3 4 
    <div data-ur-set="toggler">
      <div data-ur-toggler-component="button">Show/Hide Carousel</div>
      <div data-ur-toggler-component="content" class="carousel-toggler">
        <div data-ur-set="carousel">
          <div data-ur-carousel-component="scroll_container">
            <img data-ur-carousel-component="item" src="/images/sample1.png" alt="1">
            <img data-ur-carousel-component="item" src="/images/sample2.png" alt="2">
            <img data-ur-carousel-component="item" src="/images/sample3.png" alt="3">
            <img data-ur-carousel-component="item" src="/images/sample4.png" alt="4">
          </div>
        </div>
      </div>
    </div>
    
    .carousel-toggler:not([data-ur-state="enabled"]) {
      display: block;
      overflow: hidden;
      height: 0;
    }

Infinite Scrolling

Here we have a carousel that loops from front to back (default state for carousel). The carousel also has a custom count template, and indicator dots showing what item is currently selected. The indicator dots have a data-ur-state of "inactive" until the corresponding item is selected, when the data-ur-state changes to "active" — you can use this for styling the dots.

data-ur-carousel-component="dots"
should be within the set
Example The Code
-- count -- Prev Next
1 2 3 4 5 6 7 8 
    <div data-ur-set="carousel" data-ur-infinite="enabled">
      <div data-ur-carousel-component="dots"></div>
      <span data-ur-carousel-component="count" data-ur-template="{{index}}/{{count}}"></span>
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="prev">Prev</a>
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="next">Next</a>
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="images/sample1.png" alt="1">
        <img data-ur-carousel-component="item" src="images/sample2.png" alt="2">
        <img data-ur-carousel-component="item" src="images/sample3.png" alt="3">
        <img data-ur-carousel-component="item" src="images/sample4.png" alt="4">
        <img data-ur-carousel-component="item" src="images/sample5.png" alt="5">
        <img data-ur-carousel-component="item" src="images/sample6.png" alt="6">
        <img data-ur-carousel-component="item" src="images/sample7.png" alt="7">
        <img data-ur-carousel-component="item" src="images/sample8.png" alt="8">
      </div>
    </div>

Autoscroll

Here we have a carousel that automatically scrolls to the next item. The default is every 5 seconds, but you can specify the time using the attribute listed below.

data-ur-autoscroll="enabled"
apply this to the set
data-ur-autoscroll-delay="5000"
apply this to the set (value is in milliseconds)
Example The Code
Prev Next
1 2 3 4 5 6 7 8 
    <div data-ur-set="carousel" data-ur-autoscroll="enabled">
      <span data-ur-carousel-component="count"></span>
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="prev">Prev</a>
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="next">Next</a>
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="images/sample1.png" alt="1">
        <img data-ur-carousel-component="item" src="images/sample2.png" alt="2">
        <img data-ur-carousel-component="item" src="images/sample3.png" alt="3">
        <img data-ur-carousel-component="item" src="images/sample4.png" alt="4">
        <img data-ur-carousel-component="item" src="images/sample5.png" alt="5">
        <img data-ur-carousel-component="item" src="images/sample6.png" alt="6">
        <img data-ur-carousel-component="item" src="images/sample7.png" alt="7">
        <img data-ur-carousel-component="item" src="images/sample8.png" alt="8">
      </div>
    </div>

Autofill

Here we have a carousel that forces a set number of items to fill the container with equal widths.

data-ur-fill="5"
apply this to the set
Example The Code
Prev Next
1 2 3 4 5 6 7 8 
    <div data-ur-set="carousel" data-ur-fill="5" data-ur-infinite="disabled">
      <div data-ur-carousel-component="dots"></div>
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="prev">Prev</a>
      <a data-ur-carousel-component="button" data-ur-carousel-button-type="next">Next</a>
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="images/sample1.png" alt="1">
        <img data-ur-carousel-component="item" src="images/sample2.png" alt="2">
        <img data-ur-carousel-component="item" src="images/sample3.png" alt="3">
        <img data-ur-carousel-component="item" src="images/sample4.png" alt="4">
        <img data-ur-carousel-component="item" src="images/sample5.png" alt="5">
        <img data-ur-carousel-component="item" src="images/sample6.png" alt="6">
        <img data-ur-carousel-component="item" src="images/sample7.png" alt="7">
        <img data-ur-carousel-component="item" src="images/sample8.png" alt="8">
      </div>
    </div>