Flickity beta

• Download flickity.​pkgd.​min.js
• Download flickity.​css
• Download these docs
• Flickity on GitHub

Install

Download

• JavaScript: flickity.pkgd.js uncompressed or flickity.pkgd.min.js minified
• CSS: flickity.css

Package managers

Install with Bower: bower install flickity --save

Install with npm: npm install flickity

Getting started

Include the Flickity .css and .js files in your site.

<link rel="stylesheet" href="/path/to/flickity.css" media="screen">

<script src="/path/to/flickity.pkgd.min.js"></script>

Flickity works on a container gallery element with a group of cell elements.

<div id="main-gallery">
  <div class="gallery-cell">...</div>
  <div class="gallery-cell">...</div>
  <div class="gallery-cell">...</div>
  ...
</div>

There are several ways to initialize Flickity.

Initialize with jQuery

You can use Flickity as a jQuery plugin: $('selector').flickity().

$('#main-gallery').flickity({
  // options
  cellAlign: 'left',
  contain: true
});

Initialize with Vanilla JavaScript

You can use Flickity with vanilla JS: new Flickity( elem ). The Flickity() constructor accepts two arguments: the gallery element and an options object.

var elem = document.querySelector('#main-gallery');
var flicky = new Flickity( elem, {
  // options
  cellAlign: 'left',
  contain: true
});

// element argument can be a selector string
//   for an individual element
var flicky = new Flickity( '#main-gallery', {
  // options
});

Initialize with HTML

You can initialize Flickity in HTML, without writing any JavaScript. Add js-flickity to the class of the gallery element. Options can be set with a data-flickity-options attribute.

<div id="main-gallery" class="js-flickity"
  data-flickity-options='{ "cellAlign": "left", "contain": true }'>

Cell style

All sizing and styling of the cells are handled by your own CSS.

/* cells will take up entire width of container */
.gallery-cell {
  width: 100%;
  height: 140px;
}

/* half-width cells with margin */
.gallery-cell {
  width: 50%;
  height: 140px;
  margin-right: 10px;
}

Cells can be different sizes. You can use any unit you like: percent, pixels, etc.

.gallery-cell {
  width: 33%;
  height: 140px;
  margin-right: 10px;
}
.gallery-cell.size-180 { width: 180px; }
.gallery-cell.size-large { width: 75%; }

You can use media queries to show different number of cells for different breakpoints.

.gallery-cell {
  width: 100%;
  height: 140px;
  margin-right: 2%;
}

@media screen and ( min-width: 768px; ) {
  /* show 2 cells for larger devices */
  .gallery-cell { width: 49%; }
}

Options

cellAlign

Align cells within the gallery element.

• Values: 'center', 'left', 'right'
• Default: 'center'

cellAlign: 'left'

// default 'center'

cellAlign: 'right'

wrapAround

At the end of cells, wrap-around to the other end for infinite scrolling.

• Values: true, false
• Default: false

wrapAround: true

contain

Contains cells to gallery element to prevent excess scroll at beginning or end. Has no effect if wrapAround: true.

• Values: true, false
• Default: false

contain: true

freeScroll

Enables content to be freely scrolled and flicked without aligning cells to an end position.

• Values: true, false
• Default: false

freeScroll: true

Enable freeScroll and contain for a simple horizontal scroller.

freeScroll: true,
contain: true,
// disable previous & next buttons and dots
prevNextButtons: false,
pageDots: false

Enable freeScroll and wrapAround and you can flick forever, man.

freeScroll: true,
wrapAround: true

autoPlay

Automatically advances to the next cell. Delay is 3 seconds if autoPlay: true. Set delay time in milliseconds, for example autoPlay: 1500 will advance every 1.5 seconds.

Auto-playing will pause when mouse is hovered over, and resume when mouse is hovered off. Auto-playing will stop when the gallery is clicked or a cell is selected.

• Values: true, false, Integer
• Default: false

autoPlay: true

watchCSS

You can enable and disable Flickity with CSS. watchCSS option watches the content of :after of the gallery element. Flickity is enabled if :after content is 'flickity'.

IE8 and Android 2.3 do not support watching :after. Flickity will be disabled when watchCSS: true. Set watchCSS: 'fallbackOn' to enable Flickity for these browsers.

• Values: true, false, 'fallbackOn'
• Default: false

watchCSS: true

/* enable Flickity by default */
.gallery:after {
  content: 'flickity';
  display: none; /* hide :after */
}

@media screen and ( min-width: 768px ) {
  /* disable Flickity for large devices */
  .gallery:after {
    content: '';
  }
}

Images

Flickity makes beautiful image galleries.

<div class="gallery js-flickity"
  data-flickity-options='{ "imagesLoaded": true, "percentPosition": false }'>
  <img src="orange-tree.jpg" alt="orange tree" />
  <img src="submerged.jpg" alt="submerged" />
  <img src="look-out.jpg" alt="look-out" />
  ...
</div>

imagesLoaded

Unloaded images have no size, which can throw off cell positions. To fix this, the imagesLoaded option re-positions cells once their images have loaded.

• Values: true, false
• Default: false

imagesLoaded: true

<script src="/path/to/imagesloaded.pkgd.js"></script>

Other options

Defaults shown.

accessibility: true,
// enable keyboard navigation, pressing left & right keys

cellSelector: undefined,
// specify selector for cell elements

draggable: true,
// enables dragging & flicking

initialIndex: 0,
// zero-based index of the initial selected cell

percentPosition: true,
// sets positioning in percent values, rather than pixels
// Enable if items have percent widths
// Disable if items have pixel widths, like images

pageDots: true,
// enables page dots

prevNextButtons: true,
// creates and enables buttons to click to previous & next cells

resizeBound: true,
// listens to window resize events to adjust size & positions

rightToLeft: false
// enables right-to-left ordering for right-to-left languages

Previous & next buttons

Style and position previous & next buttons with CSS.

/* big buttons, no circle */
.flickity-prev-next-button {
  width: 100px;
  height: 100px;
  background: transparent;
}
/* arrow color */
.flickity-prev-next-button .arrow {
  fill: white;
}
.flickity-prev-next-button.no-svg {
  color: white;
}
/* hide disabled button */
.flickity-prev-next-button:disabled {
  display: none;
}

/* smaller, dark, rounded square */
.flickity-prev-next-button {
  width: 30px;
  height: 30px;
  border-radius: 5px;
  background: #333;
}
/* arrow color */
.flickity-prev-next-button .arrow {
  fill: white;
}
.flickity-prev-next-button.no-svg {
  color: white;
}
/* position outside */
.flickity-prev-next-button.previous {
  left: -40px;
}
.flickity-prev-next-button.next {
  right: -40px;
}

Page dots

Style and position page dots with CSS.

/* position dots in gallery */
.flickity-page-dots {
  bottom: 0px;
}
/* white circles */
.flickity-page-dots .dot {
  width: 12px;
  height: 12px;
  opacity: 1;
  background: transparent;
  border: 2px solid white;
}
/* fill-in selected dot */
.flickity-page-dots .dot.is-selected {
  background: white;
}

/* position dots up a bit */
.flickity-page-dots {
  bottom: -22px;
}
/* dots are lines */
.flickity-page-dots .dot {
  height: 4px;
  width: 40px;
  margin: 0;
  border-radius: 0;
}

License

Flickity is currently in development, v0. It is licensed GPL v3. With v1, Flickity will be dual-licensed: GPL, and a commercial license that exempts GPL.