Famo.us Carousel

A responsive carousel / slideshow / slider powered by Famo.us. Supports mouse, touch/swipe and keyboard navigation.

BREAKING CHANGES: 1.0.0 introduces customizable transitions with an updated data format. Refer to the documentation and the example project.

After cloning the repo:

npm install

Start the example project at port 8080:

npm run example

Usage

famous-carousel uses Browserify require. Refer to the example folder for boilerplate setup. Also supported are ES6 imports as well as a global version:

//-------------------------------------------------
// CommonJS:
var Carousel = require("famous-carousel").Carousel;

// or...
//-------------------------------------------------
// ES6:
import { Carousel } from "famous-carousel";

// or...
//-------------------------------------------------
// Global (boo)
var Carousel = famousCarousel.default( {...} );

// Then create a new instance of the Carousel:
var myCarousel = new Carousel("myDivSelector", {
                        // add options here
                        // ...
                    }
                );

Carousel Options

The following keys are supported in the options object. Only carouselData is required, all others are optional.

• selector

Type: String or Object Default: body As a string, selector is a CSS selector of the element to render into. As an object, selector is assumed to be a Famous node. The node's container should have overflow set to hidden.

• carouselData (required)

Type: Object This specifies the content of the slides and optional custom transitions. The transitions key specifies the global entry and exit transitions. Each slide may have its own transitions which overrides the global ones.

"transitions": {
    "initialAlign": [x, y, z],  // 0 < x, y, z < 1
    "initialPosition": [x, y, z],
    "initialRotation": [x, y, z],  // 0 < x, y, z < 1
    "entryTransition": {
        "transform": string, // "align", "rotate", "position"
        "transformParams": [x, y, z],
        "curve": string, // famous fixed curves
        "duration" : number, // ms
    },
    "exitTransition": {
        // Same keys as entryTransition
    }
}

The slides key is an array of objects, each containing type, data, and optionally backgroundSize & transition keys. type: may be image, markup, or node. data: must be a url for image, any valid html for markup, or a Famo.us node object. class: [optional] (array or string) CSS class to apply to the slide. backgroundSize: [optional] CSS background-size attribute (default contain) transition: [optional] custom transition for the given slide only (see above for format). Example data:

"slide": {
    [
        {   "type": "image",
            "data": "http://myDomain/myPicture.jpg",
            "backgroundSize": "cover"
        },
        {   "type": "markup",
            "data": "<div style='color:blue'>Hello World<BR><BR>It's me!</div>"
        },
        {   "type": "node",
            "data": myFamousNode
        }
    ]
}

• animStartCallback

Type: Function (node, index) Callback fires when a slide starts to move into the center position. Parameters (node, index) are the slide's node and its corresponding carouselData index.

• animDoneCallback

Type: Function (node, index) Callback fires when a slide has finished settling in the center visible position. Parameters (node, index) are the visible slide's node and its corresponding carouselData index.

• initialIndex

Type: Integer Default: 0 Initial slide number to show (zero-based). If larger than the number of slides, it will cap to the final slide.

• wrapAround

Type: Boolean Default: false By default, navigation stops at the ends of the slide set. Setting wrapAround to true allows navigation to wrap from one end to the other.

• autoPlay

Type: Integer Default: 0 Automatically transition slides, pausing on each slide for the number of milliseconds specified. When the user navigates manually, automatic playback stops.

• autoSlidesToAdvance

Type: Integer Default: 1 Number of slides to advance during automatic playback.

• manualSlidesToAdvance

Type: Integer Default: 1 Number of slides to advance when user navigates.

• dotWidth

Type: Integer Default: 10 Width of dots along bottom.

• dotSpacing

Type: Integer Default: 5 Spacing of dots along bottom.

• dotForeColor

Type: String Default: "white" Navigation dot foreground color (CSS style).

• dotBackColor

Type: String Default: "transparent" Navigation dot background color (CSS style).

• dotOpacity

Type: Float Default: 1.0 Navigation dot opacity (CSS style).

• dotSelectedClass

Type: String CSS class to style the selected dot. This overrides the other dot* CSS options (dotWidth & dotSpacing continue to be honored).

• dotUnselectedClass

Type: String CSS class to style unselected dots. This overrides the other dot* CSS options (dotWidth & dotSpacing continue to be honored).

• arrowFillColor

Type: String Default: "white" Navigation arrow fill color (CSS style).

• arrowOutlineColor

Type: String Default: "transparent" Navigation arrow outline color (CSS style).

• arrowClass

Type: String CSS class to style dots. This overrides the other arrow* CSS options.

Public methods

• updateData()

Updates the slide data. This calls clearSlides() to reinitialize the slides. There is an issue with the dots not re-rendering properly.

• clearSlides()

Removes the slides.

• clearAll()

Removes the carousel instance entirely. NOTE: Famo.us 0.5.2 has a bug causing it not to remove the DOMElement. famous-carousel removes the div.famous-dom-renderer element for now.

Building

To build self-contained bundles:

$ npm run build

Builds

• CommonJS version (dist/famous-carousel.min.js)

• global version (dist/global/famous-carousel.min.js), and global debug version (dist/global/famous-carousel.debug.js).
  The global build uses the variable name famousCarousel.
  To see the global version in action open browser to local port 8080/global.html after:

  $ npm run example

To build optional es5 code:

 $ npm install -g babel
 $ npm run build-es5

Run tests (~~linter &~~ style checks for now):

npm run test

FAQ

Q: The arrows & dots show, but the slides are invisible. A: famous-carousel sizes to its container's dimensions. Due to CSS box model rules, if no height is specified for the container, the default auto height computes to 0. Short answer: set a height for its parents all the way up to the root element.

Q: The slides appear from outside the containing element when animating. A: Famous-carousel sets the container's overflow property to hidden. Check if something has overridden that property.

Q: How to center the slides? A: Create a parent div of the container and set these properties:

.myContainersParent {
    overflow:hidden;
    position:absolute;
    left:0; right:0;
    top:0; bottom:0;
    margin:auto;
}

Q: The arrows/dots aren't visible [against a white background]. A: dotBackColor and arrowOutlineColor default to transparent. Set them to a different color.

Q: The slides are shifted down and to the right. A: The selector element must not have any padding. The work-around for this Famous engine bug is to wrap the selector element in a container element which has the padding. Remove all padding from the selector element. See example/index.html for... an example.

Q: Safari allows the user to vertically drag the page. How do I stop that? A: Touch events on the body must be disabled. A ready to use solution is iNoBounce.

Q: I upgraded the famous-carousel version and everything broke. A1: Delete node_modules and run npm install again. A2: Check that the data format matches what is required by the given version of famous-carousel.

To Do

Pull requests are welcome. When submitting a PR, please make sure npm run test passes.

• Unit tests.
• ~~Add exit transition.~~
• Add more user-configurable options such as ~~slide transitions~~, nav arrow images...
• Re-implement physics option for customizable transitions.
• Option to auto-hide navigation arrows & dots.
• Navigate by clicking on dots.
• Auto start/stop videos in slides.
• Option for vertical scrolling.
• Support CSS class for slides?

License

This project is based on the Famo.us Carousel tutorial and bound by the same MIT license. Refer to the LICENSE file.