An AngularJS module that exposes a directive and service to create and control multiple Flickity instances.
Comments and pull requests welcome!
- Installation
- Usage
- Options
- ID
- Global Defaults
- Directives
- Services
- Events
- Demos
- Development
- About Flickity
- AngularJS
(^1.4.0)
- Flickity
(^2.0.5)
- flickity-imagesloaded
(^2.0.0)
(if using the imagesloaded option) - flickity-bg-lazyload
(^1.0.0)
(if using the bgLazyLoad option)
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 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 Flickity
(and flickity-imagesloaded
/flickity-bg-lazyload
if needed):
import Flickity from 'flickity';
import 'flickity-imagesloaded';
import 'flickity-bg-lazyload';
import 'angular-flickity';
angular.module('myProject', ['bc.Flickity']);
<!-- Include the module -->
<script src="path/to/lib/flickity.js"></script>
<script src="path/to/lib/flickity-imagesloaded.js"></script>
<script src="path/to/lib/flickity-bg-lazyload.js"></script>
<script src="path/to/angular-flickity/dist/angular-flickity.js"></script>
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"
]
}
}
}
Include bc.Flickity
as a dependency in your project.
angular.module('YourModule', ['bc.Flickity']);
Use the directive on the parent element containing your slides.
<!-- Define the gallery: -->
<div
bc-flickity="{{ vm.flickityOptions }}"
id="myCustomId"
>
<figure class="demo__slide" data-ng-repeat="slide in vm.slides">
<img data-ng-src="{{ slide }}" alt="" />
</figure>
</div>
<!-- Define the previous button (optional): -->
<button
bc-flickity-previous
bc-flickity-id="myCustomId"
>Previous</button>
<!-- Define the next button (optional): -->
<button
bc-flickity-next
bc-flickity-id="myCustomId"
>Next</button>
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
:
<!-- In your template -->
<div bc-flickity="{{ myCustomOptions }}">
<div class="mySlideClassName"></div>
<div class="mySlideClassName"></div>
...
</div>
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.
If the element containing the bc-flickity
directive has an ID attribute, the value will
be used to create the ID.
<!-- This instance would have the ID of `foo` -->
<div
bc-flickity="{{ myCustomOptions }}"
id="foo"
>
<!-- slides -->
</div>
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
.
<!-- This instance would have the ID of `bar` -->
<div
bc-flickity="{{ myCustomOptions }}"
bc-flickity-id="bar"
>
<!-- slides -->
</div>
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;
})
;
The directive bc-flickity
creates the Flickity gallery.
<div bc-flickity>
<!-- slides -->
</div>
You may optionally pass an options object to the directive. User defined options will override any default options.
<div bc-flickity="{{ vm.flickityOptions }}">
<!-- slides -->
</div>
Learn more about
angular-flickity
options & Flickity options documentation
The directive bc-flickity-next
is provided to call the next()
method on a Flickity
instance.
<button bc-flickity-next>Next</button>
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>
If no ID is set, the directive will assume that only one instance exists and grab the ID from the first instance.
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>
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 totrue
. - The directive has
true
passed in as the optional parameter (which overrides the default options).
The directive bc-flickity-previous
is provided to call the previous()
method on the Flickity
instance.
<button bc-flickity-previous>Previous</button>
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>
If no ID is set, the directive will assume that only one instance exists and grab the ID from the first instance.
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>
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 totrue
. - The directive has
true
passed in as the optional parameter (which overrides the default options).
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 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).
Don't be afraid to look at the source code. It isn't terribly complicated and fairly well commented.
This can be called to manually create a new Flickity
instance.
FlickityService.create(element, id, options)
element
:{Element}
- A DOM element wrapped as a jQuery object. This can be done with jqLite
(
angular.element(element)
) or jQuery ($(element)
)
- A DOM element wrapped as a jQuery object. This can be done with jqLite
(
id
:{String}
optional- ID for the created
Flickity
instance. If no ID is assigned, one will be created and used internally.
- ID for the created
options
:{Object}
optional- Options object for Flickity
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.
// 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.
// 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);
});
});
Move directly to a specific slide.
FlickityService.select(id, index, isWrapped, isInstant)
id
:{String}
- A string representing the ID of the
Flickity
instance to move.
- A string representing the ID of the
index
:{Number}
isWrapped
:{Bool}
optional- Default:
false
- If
true
andprevious
is called when on the first slide, the slider will wrap around to show the last slide. - If
true
andnext
is called when on the last slide, the slider will wrap back to show slide 1.
- Default:
isInstant
:{Bool}
optional- Default:
false
- If
true
the slide will change instantly with no animation.
- Default:
instance
:{Object}
Move to the previous slide.
FlickityService.previous(id, isWrapped, isInstant)
id
:{String}
- A string representing the ID of the
Flickity
instance to move.
- A string representing the ID of the
isWrapped
:{Bool}
optional- Default:
false
- If
true
andprevious
is called when on the first slide, the slider will wrap around to show the last slide. - If
false
andprevious
is called when on the first slide, the slider will do nothing.
- Default:
isInstant
:{Bool}
optional- Default:
false
- If
true
the slide will change instantly with no animation.
- Default:
instance
:{Object}
Move to the next slide.
FlickityService.next(id, isWrapped, isInstant)
id
:{String}
- A string representing the ID of the
Flickity
instance to move.
- A string representing the ID of the
isWrapped
:{Bool}
optional- Default:
false
- If
true
andnext
is called when on the last slide, the slider will wrap back to show slide 1. - If
false
andnext
is called when on the last slide, the slider will do nothing.
- Default:
isInstant
:{Bool}
optional- Default:
false
- If
true
the slide will change instantly with no animation.
- Default:
instance
:{Object}
Select a slide of a cell.
FlickityService.cellSelect(id, value, isWrapped, isInstant)
id
:{String}
- A string representing the ID of the
Flickity
instance to move.
- A string representing the ID of the
value
:{Integer|String}
- Zero-based index OR selector string of the cell to select.
isWrapped
:{Bool}
optional- Default:
false
- If
true
andprevious
is called when on the first slide, the slider will wrap around to show the last slide. - If
true
andnext
is called when on the last slide, the slider will wrap back to show slide 1.
- Default:
isInstant
:{Bool}
optional- Default:
false
- If
true
the slide will change instantly with no animation.
- Default:
instance
:{Object}
Triggers Flickity to resize the gallery and re-position cells.
FlickityService.resize(id)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
instance
:{Object}
Tell Flickity to reposition cells while retaining the current index. Useful if cell sizes change after initialization.
FlickityService.reposition(id)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
instance
:{Object}
Note: If you are trying to add cell(s) by appending to a 'slides' array and then reinitializing the slider, take a look at this πΊ demo
Create cells at the beginning of the gallery and prepend elements.
FlickityService.prepend(id, elements)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
elements
:{Object|Array|Element|NodeList}
- jQuery object, Array of Elements, Element, or NodeList
instance
:{Object}
Create cells at the end of the gallery and append elements.
FlickityService.append(id, elements)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
elements
:{Object|Array|Element|NodeList}
- jQuery object, Array of Elements, Element, or NodeList
instance
:{Object}
Insert elements into the gallery and create cells at the desired index.
FlickityService.insert(id, elements, index)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
elements
:{Object|Array|Element|NodeList}
- jQuery object, Array of Elements, Element, or NodeList
index
:{Integer}
- Zero based integer where the new slides should be inserted.
instance
:{Object}
Remove cells from the gallery and remove the elements from DOM.
FlickityService.remove(id, elements)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
elements
:{Object|Array|Element|NodeList}
- jQuery object, Array of Elements, Element, or NodeList
instance
:{Object}
Destroys a Flickity
instance.
FlickityService.destroy(id)
id
:{String}
- A string representing the ID of the
Flickity
instance to be destroyed.
- A string representing the ID of the
isDestroyed
:{Bool}
This is very useful when your Flickity instance is created inside a controller attached to a route. Each time the route is hit, the route's controller calls to create a new Flickity instance. But if that instance already exists, it will cause an error. The correct way to handle this is to destroy the Flickity instance when the controller is being destroyed.
$scope.$on('$destroy', () => {
FlickityService.destroy(instanceId);
});
Re-collect all cell elements in flickity-slider
.
FlickityService.reloadCells(id)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
instance
:{Object}
Note: If you are trying to add cell(s) by appending to a 'slides' array and then reinitializing the slider, take a look at this πΊ demo
Get the elements of the cells.
FlickityService.getCellElements(id)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
cellElements
:{Array}
Return a Flickity
instance found by ID.
FlickityService.get(id)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
instance
:{Object}
Return the first Flickity
instance.
FlickityService.getFirst()
instance
:{Object}
Find a Flickity
instance by element or selector string.
FlickityService.getByElement(id, element)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
element
:{Element}
- Element or selector string representing the
Flickity
instance.
- Element or selector string representing the
instance
:{Object}
Get the index of the slide currently in view.
FlickityService.selectedIndex(id)
id
:{String}
- A string representing the ID of the
Flickity
instance for which you need the index.
- A string representing the ID of the
selectedIndex
:{Number}
- The index of the currently visible slide.
Get the currently selected cell element.
FlickityService.selectedElement(id)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
selectedElement
:{Element}
Get all cells.
FlickityService.cells(id)
id
:{String}
- A string representing the ID of the
Flickity
instance.
- A string representing the ID of the
cells
:{Array}
All events trigger an associated $emit
on $rootScope
.
Learn more in the Angular docs on
$emit
.
Each $emit
event is named in this format: Flickity:[instanceId]:[eventName]
So, for example, if you had declared a custom ID of myCustomId
on bc-flickity
and wanted
to know when the settle
event occurs, you could listen for it like this:
// Assume the gallery has been initialized with the custom ID of `myCustomId`
const settle = $rootScope.$on('Flickity:myCustomId:settle', (event, data) => {
console.log('Flickity just settled!', event, data);
});
For more information on individual events, check out the Flickity Documentation on Events.
// Legend
β’ eventName
β’ parameter
select
scroll
progress
positionX
settle
dragStart
event
pointer
dragMove
event
pointer
moveVector
dragEnd
event
pointer
pointerDown
event
pointer
pointerMove
event
pointer
moveVector
pointerUp
event
pointer
staticClick
event
pointer
cellElement
cellIndex
lazyLoad
event
cellElement
eventName
=> Flickity:instanceId:eventName
Event name | $emit name |
---|---|
select |
Flickity:instanceId:select |
scroll |
Flickity:instanceId:scroll |
settle |
Flickity:instanceId:settle |
dragStart |
Flickity:instanceId:dragStart |
dragMove |
Flickity:instanceId:dragMove |
dragEnd |
Flickity:instanceId:dragEnd |
pointerDown |
Flickity:instanceId:pointerDown |
pointerMove |
Flickity:instanceId:pointerMove |
pointerUp |
Flickity:instanceId:pointerUp |
staticClick |
Flickity:instanceId:staticClick |
lazyLoad |
Flickity:instanceId:lazyLoad |
Learn more about Flickity events.
Don't forget:
The $on
call should always be assigned to a variable. This allows it to be destroyed during the
$scope
cleanup.
Learn more about $destroy.
- All demos
- Simple
- Multiple instances on a page
- Using events
- Using the service and selecting a cell
- Create via the service and loading remote data
- Inject a slide
- bgLazyLoad
npm run build
- Produces uncompressed (
.js
) and minified (.min.js
) versions of the library under thedist
folder.
- Produces uncompressed (
npm run watch
- Watches for changes inside
/src
and callsnpm run build
when changes are detected.
- Watches for changes inside
npm run test
- Runs all tests.
npm run watch:tests
- Watch for changes and re-run tests.
Touch, responsive, flickable galleries.