Angular Flickity

[![MIT License][license_image]][license_url] [![Coverage Status][coverage_image]][coverage_url] [![NPM version][npm_version_image]][npm_url] [![CircleCI][circle_badge]][circle_link]

An AngularJS module that exposes a directive and service to create and control multiple [Flickity][flickity] instances.

[:tv: Demos and Examples][demo_collection]

[Flickity][flickity] by [Metafizzy][metafizzy]

[Comments and pull requests welcome!][issues]

Contents

• Installation
• Dependencies
• Usage
• Options
• ID
• Global Defaults
• Directives
  • bc-flickity
  • bc-flickity-next
  • bc-flickity-previous
• Services
  • Initialize
    • create
  • Selecting Cells
    • select
    • previous
    • next
  • Sizing and Positioning
    • resize
    • reposition
  • Adding and Removing Cells
    • prepend
    • append
    • insert
    • remove
  • Utilities
    • destroy
    • reloadCells
    • getCellElements
    • get
    • getFirst
    • getByElement
  • Properties
    • selectedIndex
    • selectedElement
    • cells
• Events
• Events and Parameters
• Event Naming Convention
• Demos
• Development
• About Flickity

---

Installation

Dependencies

• [AngularJS (^1.4.0)][angular]
• [Flickity (^2.0.5)][flickity_docs]
• [flickity-imagesloaded (^2.0.0)][flickity_imagesloaded] (if using the [imagesloaded option][flickity_options])
• [flickity-bg-lazyload (^1.0.0)][flickity-bg-lazyload] (if using the [bgLazyLoad option][flickity_options])

NPM

npm install flickity --save
npm install flickity-imagesloaded --save # if using the imagesloaded option
npm install flickity-bg-lazyload --save # if using the bg-lazyload option
npm install angular-flickity --save

Bower

bower install flickity --save
bower install flickity-imagesloaded --save # if using the imagesloaded option
bower install flickity-bg-lazyload --save # if using the bg-lazyload option
bower install angular-flickity --save

Include the scripts

Include Flickity (and flickity-imagesloaded/flickity-bg-lazyload if needed):

Webpack

import Flickity from 'flickity';
import 'flickity-imagesloaded';
import 'flickity-bg-lazyload';
import 'angular-flickity';

angular.module('myProject', ['bc.Flickity']);

Manually

<script src="https://github.com/benjamincharity/angular-flickity/raw/v3.1.4/path/to/lib/flickity.js"></script>
<script src="https://github.com/benjamincharity/angular-flickity/raw/v3.1.4/path/to/lib/flickity-imagesloaded.js"></script>
<script src="https://github.com/benjamincharity/angular-flickity/raw/v3.1.4/path/to/lib/flickity-bg-lazyload.js"></script>
<script src="https://github.com/benjamincharity/angular-flickity/raw/v3.1.4/path/to/angular-flickity/dist/angular-flickity.js"></script>

Note when using Flickity via bower

In my experience, including Flickity through bower often doesn't work out of the box. By default, bower pulls in the unpackaged files as the Flickity bower.json specifies rather than packaged files which seems to be what we need.

The trick is to specify which files bower should use in your own bower.json.

// inside your bower.json specify which Flickity files to use
{
  "name": "myProject",
  "overrides": {
    "flickity": {
      "main": [
        "dist/flickity.pkgd.js",
        "dist/flickity.min.css"
      ]
    }
  }
}

Usage

Include bc.Flickity as a dependency in your project.

angular.module('YourModule', ['bc.Flickity']);

Use the directive on the parent element containing your slides.

  <figure class="demo__slide" data-ng-repeat="slide in vm.slides">
      <img data-ng-src="https://github.com/benjamincharity/angular-flickity/raw/v3.1.4/{{ slide }}" alt="" />
  </figure>





<button
  bc-flickity-previous
  bc-flickity-id="myCustomId"
>Previous</button>


<button
  bc-flickity-next
  bc-flickity-id="myCustomId"
>Next</button>

Options

This module supports all options for Flickity version 2.0.5. A full list of options can be found here: Flickity Options.

Simply pass in an object containing any options you'd like to set.

// ES5 example
angular.module('myModule')
  .controller('MyController', ($scope) => {

    $scope.myCustomOptions = {
      cellSelector: '.mySlideClassName',
      initialIndex: 3,
      prevNextButtons: false,
    };

  })
;


// ES6 example
export class MyController {
  constructor() {

    this.flickityOptions = {
      cellSelector: '.mySlideClassName',
      initialIndex: 3,
      prevNextButtons: false,
    };

  }
}

my.template.html:

  ...

ID

The FlickityService uses IDs to manage multiple instances of the directive. An ID is automatically created and assigned at initialization. However, at times you may need to access your instances in a programmatic way. There are two ways for IDs to be defined by your module.

Element ID

If the element containing the bc-flickity directive has an ID attribute, the value will be used to create the ID.

Explicitly Define

At times, you may not be able to use an element ID (or simply prefer not to). In those cases you can pass the ID in directly as a string using bc-flickity-id.

Global Defaults

This module exposes FlickityConfigProvider which can be used to set project-wide defaults for Flickity. Simply set any options here using options that match the original Flickity options.

// ES6 Config Example
export function config(FlickityConfigProvider) {
    'ngInject';

    FlickityConfigProvider.prevNextButtons = true;
    FlickityConfigProvider.setGallerySize = false;

}

// ES5 Config Example
angular.module('myModule')
    .config((FlickityConfigProvider) => {
        'ngInject';

        FlickityConfigProvider.prevNextButtons = true;
        FlickityConfigProvider.setGallerySize = false;

    })
;

Directives

bc-flickity

The directive bc-flickity creates the Flickity gallery.

You may optionally pass an options object to the directive. User defined options will override any default options.

Learn more about angular-flickity options & [Flickity options documentation][flickity_options]

bc-flickity-next

The directive bc-flickity-next is provided to call the next() method on a Flickity instance.

<button bc-flickity-next>Next</button>

Multiple Instances

If you need to support multiple Flickity instances in a single view you can specify an instance ID that the control should be linked to.

<button
  bc-flickity-next
  bc-flickity-id="customId"
>Next</button>

More on setting the ID using a directive or service.

If no ID is set, the directive will assume that only one instance exists and grab the ID from the first instance.

Looping

This directive accepts an optional parameter to control the looping. If true and at the last cell when clicked, Flickity will loop back to the first cell. If false, it will do nothing when clicked at the last cell.

<button bc-flickity-next="true">Next</button>

Disabled

When the last cell is reached, the disabled attribute will be added to the element. The disabled attribute will not be added if either of these conditions are met:

• The associated gallery has wrapAround set to true.
• The directive has true passed in as the optional parameter (which overrides the default options).

bc-flickity-previous

The directive bc-flickity-previous is provided to call the previous() method on the Flickity instance.

<button bc-flickity-previous>Previous</button>

Multiple Instances

If you need to support multiple Flickity instances in a single view you can specify an instance ID that the control should be linked to.

<button
  bc-flickity-next
  bc-flickity-id="customId"
>Next</button>

More on setting the ID using a directive or service.

If no ID is set, the directive will assume that only one instance exists and grab the ID from the first instance.

Looping

This directive accepts an optional parameter to control the looping. If true and at the first cell when clicked, Flickity will loop around to the last cell. If false, it will do nothing when clicked at the first cell.

<button bc-flickity-previous="true">Previous</button>

Disabled

When at the first cell, the disabled attribute will be added to the element. The disabled attribute will not be added if either of these conditions are met:

• The associated gallery has wrapAround set to true.
• The directive has true passed in as the optional parameter (which overrides the default options).

---

Services

While you can easily use Flickity via the directive only, most Flickity methods are accessible via the FlickityService.

The services here follow the order of the [Flickity Documentation][flickity_api] as closely as possible in order to be immediately familiar. This shouldn't feel like learning another library (assuming you are already familiar with Flickity).

[:tv: Service demo][demo_service_select]

---

Don't be afraid to look at the [source code][source]. It isn't terribly complicated and fairly well commented.

Initialize

create

This can be called to manually create a new Flickity instance.

[:tv: Create instance demo][demo_create_remote_docready]

FlickityService.create(element, id, options)

Parameters

• element: {Element}
• A DOM element wrapped as a jQuery object. This can be done with jqLite (angular.element(element)) or jQuery ($(element))
• id: {String} optional
• ID for the created Flickity instance. If no ID is assigned, one will be created and used internally.
• options: {Object} optional
• Options object for Flickity

Returns Promise

• instance: {Object}

// Example return
{
    id: 'foo',
    instance: Flickity
};

NOTE: Anytime you are dealing with the DOM from inside a controller (:-1:) make sure to use document.ready. This ensures that the element you are looking for actually exists. You can also use a $timeout but I find using document.ready more accurately represents the intention.

[:tv: Demo showing DOM issue and solution][demo_create_remote_docready]

// document.ready example
angular.element($document[0]).ready(() => {
    // Get the element that should hold the slider
    const element = angular.element(document.getElementById('demo-slider'));

    // Initialize our Flickity instance
    FlickityService.create(element[0], element[0].id);
});

NOTE: If you are dealing with remote data, you should wrap the .create() call with a $timeout. This ensures that the data has already been assigned to scope before the slider is initialized.

[:tv: Demo with remote data][demo_create_remote_docready]

// Remote data example
$http.get('http://yourRemoteSource.com/slides.json')
  .then((results) => {

    // Expose the slides array to $scope
    $scope.slides = results.data;

    // Get the element that should hold the slider
    const element = angular.element(document.getElementById('demo-slider'));

    // NOTE: When fetching remote data, we initialize the Flickity
    // instance inside of a $timeout. This ensures that the slides
    // have already been assigned to scope before the slider is
    // initialized.
    $timeout(() => {
      // Initialize our Flickity instance
      FlickityService.create(element[0], element[0].id);
    });
  });

Selecting Cells

select

Move directly to a specific slide.

[:tv: Selecting a cell demo][demo_service_select]

FlickityService.select(id, index, isWrapped, isInstant)

• id: {String}
• A string representing the ID of the Flickity instance to move.
• index: {Number}
• isWrapped: {Bool} optional
• Default: false
• If true and previous is called when on the first slide, the slider will wrap around to show the last slide.
• If true and next is called when on the last slide, the slider will wrap back to show slide 1.
• isInstant: {Bool} optional
• Default: false
• If true the slide will change instantly with no animation.

Returns Promise

• instance: {Object}