famous-carousel

##Famo.us Carousel

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

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. When using this as an npm module, reference it as such:

var Carousel = require('famous-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.

• carouselData (required)

Type: Object
This specifies the content of the slides. It is an array of objects, each containing type and data keys.
type may be 'image' or 'markup'.
data must be a url for image, or any valid html for markup.

• 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 a self-contained bundle:

npm run build

That builds the CommonJS version (famous-carousel.js), global version (famous-carousel.global.js), and global debug versions (famous-carousel.global.debug.js). The global build uses the variable name famousCarousel. To see the global version in action, copy dist/famous-carousel.global.js to example/, start a server in example and open global.html .

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: Set the container's overflow property to hidden. Additionally center the famous-carousel within the containing element using these properties:

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

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

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...
• Option to auto-hide navigation arrows & dots.
• Navigate by clicking on dots.
• Auto start/stop videos in slides.
• 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.