ng-slideshow v0.8.2
Angular 2+ Slideshow
A high speed, fluid and consistent image gallery slideshow target for both desktop and mobile.
There are a lot of slideshow components available on the web, although none of them matched completely my needs and requirements; so I've decided to create one. I needed a fast slideshow that doesn't block anything else occurring in the page, that uses Immutable objects as inputs and only relies on native browser support for animations and that allows for swiping on mobile.
On top of that, I wanted a slideshow that takes its size from the parent container, so I can easily manipulate it to have a real proper slideshow for different viewports.
Features:
- Uses Immutable objects as inputs thus optimizing Angular change detection mechanism
- All animations are purely CSS based
- Supports swipe events for touch devices
- All animations and slide events occur outside of the Angular zone, thus increasing FPS values
- All functionality is covered with unit tests
- Uses images as background images, meaning that the viewport is always the same size for all images
- By using images as background images it allows the slideshow to grown dynamically according to its parent container
- Only needs to have a defined height, width can be automatically calculated from the parent container
- Optionally, a list of thumbnails can be displayed below the main slide for extended navigation
- Optionally, a dot navigation style is also provided
Demo
Docs
https://voxmachina.github.io/ng-slideshow/
Requirements
Installation
npm install ng-slideshow --save
Usage
Import SlideshowModule
on your app module:
import {BrowserModule} from '@angular/platform-browser';
import {NgModule} from '@angular/core';
import {FormsModule} from '@angular/forms';
import {HttpModule} from '@angular/http';
import {AppComponent} from './app.component';
import {SlideshowModule} from 'ng-slideshow'; // IMPORT THE SLIDESHOW MODULE
@NgModule({
declarations: [
AppComponent
],
imports: [
SlideshowModule, // IMPORT THE SLIDESHOW MODULE
BrowserModule,
FormsModule,
HttpModule
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule {
}
On the component specify a list of options and a list of images to display:
import { Component } from '@angular/core';
import * as Immutable from 'immutable';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss']
})
export class AppComponent {
/**
* A list of slideshow options
*
* @type {Map<string, any>}
*/
options = Immutable.Map({
showDots: true, // Shows a dot navigation component
height: 450, // The initial slideshow height
showThumbnails: true, // Optionally include thumbnails a navigation option
thumbnailWidth: 150 // Thumbnail individual width for the thumbnail navigation component
});
/**
* A list of images, title is optional, it will be displayed when it's available
*
* All images should have a url and a title parameter, if you don't
* receive the content like this from the server you can always work out something like:
*
* datasetFromServer.map((imageData) => {
* imageData.url = imageData.serverUrl;
* imageData.title = imageData.serverTitle;
* });
*
* @type {Immutable.List<any>}
*/
images = Immutable.List([
{
url: 'http://placekitten.com/800/500',
title: 'Lorem Ipsum is simply dummy text of the printing and typesetting industry. ' +
'Lorem Ipsum has been the industrs standard dummy text ever since the 1500s, when an unknown printer ' +
'took a galley of type and scrambled it to make a type specimen book.'
},
{url: 'http://placekitten.com/1200/500'},
{url: 'http://placekitten.com/800/300', title: 'cat'},
{url: 'http://placekitten.com/300/500', title: 'cat'},
{url: 'http://placekitten.com/860/500', title: 'cat'},
{url: 'http://placekitten.com/830/500', title: 'cat'},
{url: 'http://placekitten.com/660/500', title: 'cat'},
{url: 'http://placekitten.com/720/500', title: 'cat'},
{url: 'http://placekitten.com/360/300', title: 'cat'},
{url: 'http://placekitten.com/860/860', title: 'cat'},
{url: 'http://placekitten.com/800/900', title: 'cat'},
{url: 'http://placekitten.com/800/1200', title: 'cat'}
]);
}
On the template include the component:
<h1>Slideshow Demo</h1>
<section>
<ng-slideshow [options]="options" [images]="images"></ng-slideshow>
</section>
On the stylesheet you'll need to define at least the height of your container, width is optional and when not defined it will take 100% and scale accordingly:
section {
width: 900px;
height: 450px;
}
Slideshow Options
height
: The slideshow needs a defined initial height to be displayedshowThumbnails
: Either or not to display the thumbnail navigationthumbnailWidth
: When using the thumbnail navigation, the thumbnail width must be definedshowDots
: Either or not to show the dots navigation component
Development
Feel free to participate in the development of this project, any contribution is more than welcome.
If you take a look at the main root package file, you should see the development tasks needed to get you going.
I've also included, in the source, a demo app component, so you should be able to just run npm start
to see it live, and see a demo of the slideshow.
Running unit tests
Run npm run tests-dev
to execute the unit tests via Karma, or npm run tests-ci
to execute the unit tests using a headless Chrome version.
License
MIT