NativeScript Carousel

A simple carousel component for NativeScript.

Platform	Supported	Version	NativeView
iOS	Yes	iOS 8.1+	DKCarouselView
Android	Yes	API 15+	ViewPager with PageIndicatorView

Installation

Run tns plugin add nativescript-carousel in the ROOT directory of your project. You must clean your project after adding a plugin with native dependencies. This can be done by executing tns platform remove android (or ios) and then tns platform add android (or ios). The newer versions of the NS CLI, provide a clean command that does this in one script if you like that option as well.

Limitations

• (iOS) PagerIndicator animations not available for iOS, only Android.
• (Android) Auto- and Infinite-paging not available.
• (Android) Carousel still needs to be wrapped in a GridLayout for the indicator to overlap.

Usage

Check out the demos included in this repo for instructions on how to use the Carousel with your choice of framework:

Vanilla TS demo

Angular demo

Vue demo

Attributes - Common

• items optional (must be used with itemTemplate)

Assign a data-array to generate the slides and apply the bindingContext. If items is populated then you must use the template-option.

• itemTemplate optional (must be used with items)

Defines the view template for each slide-view to be generated.

• selectedPage optional

Sets/Gets the active page by index

• showIndicator optional

Shows or hides the page-indicator

• indicatorColor optional

Sets the active indicator color. Default is semi-transparent white. Use hex or color-name.

• indicatorColorUnselected

Sets the color of unselected indicators

• indicatorOffset optional

By default the indicator is centered at the bottom. You can use points (x,y) to move the indicator. E.g. indicatorOffset="100,100"

Attributes - iOS specific

• finite optional

If true last slide will wrap back to first and visa versa

• bounce optional

If set to 'true' scrolling will bounce at the first/last page (non-infinite). Default is 'false'.

• autoPagingInterval optional

Defines the interval in seconds to wait before the next slide is shown. Default is 0 (off).

• scrollEnabled optional

Enables/Disables user scroll on the Carousel.

• ios

Returns the DKCarouselView object.

Attributes - Android specific

• android

Returns the ViewPager object.

• indicatorAnimation

Sets the pager-indicator animation type. Choose between: color, slide, scale, worm, thin_worm, fill, drop or none. Default is none.

• indicatorAnimationDuration

Sets the pager-indicator animation duration in milliseconds. Default is 500.

• indicatorAlignment

Sets the pager-indicator alignment. Choose between top or bottom. Default is bottom.

• indicatorRadius

Sets the pager-indicator dot radius.

• indicatorPadding

Sets the pager-indicator dot padding.

• pageIndicatorCount

Set the indicator count which will change the underlying Android data adapter. See issue #5 discussion

Demo

iOS	Android

Indicator animations (Android only!)

NONE	COLOR	SCALE	SLIDE

WORM	THIN_WORM	FILL	DROP	SWAP

Changelog

6.1.0

• Fix for iOS safe-area issues. No need to use the custom css-padding-hack any more.
• DKCarouselView pod updated to version 2.5.0 (fix safe-area layout).
• Known bugs: Orientation change render-issues on iOS (DKCarouselView) (help wanted).
• Demos updated.

6.0.0

• NativeScript 6.0 & AndroidX migration.
• IndicatorView gradle bumped to 1.0.3 (androidx).
• Some refactorings on the Android side for the plugin to work better with Angular & Vue.
• Demos updated, again.
• Instructions for each demo updated.

4.2.5

• Fix for the dreadded PagerAdapter changed the adapter's contents without calling PagerAdapter#notifyDataSetChanged! error on Android.
• Hotfix on the AndroidX migration.
• Minor refactor in the refresh() function. Safer to call on demand.
• Redesigned all demo apps. Added more advanced examples.
• 4.x will be the last Nativescript 5.x version. All future versions will be Nativescript 6.x only and that includes AndroidX.

4.2.1

• Hotfix for static items. Sorry!

4.2.0

• AndroidX update for NS6. Thanks @bradmartin!
• Code cleanup, typings fix.
• Demos updated. Proper Vue-demo added.

4.1.0

• Added setter for pageIndicatorCount for Android to enable dynamically changing the length of the carousel items array without Android throwing a crash about the adapster set changing incorrectly.

4.0.2

• Carousel now extends from GridLayout instead of AbsoluteLayout (better positioning). (Thanks @bradmartin)

4.0.0

• Mirgration to TypeScript, typings added (Thanks @bradmartin)
• Cleanup in demo app, added ng-demo (Thanks @bradmartin)

3.1.1

• Made comaptible for recent TNS 3.2.x releases.
• Merged fix regarding the notifyDataSetChanged issue. Thanks @OPADA-Eng
• Fixed issue on iOS when having only 2 slides. Thanks @sitefinitysteve

3.1.0

• Made comaptible for recent TNS 3.1.x releases.
• Updated Android indicator library to latest version.

3.0.2

• Fixed an issue with events not working on Android (affected all events).

3.0.1

• Fixed a critical bug on Android during refresh when navigating back to a view with a Carousel.

3.0.0

• Finally! Support for TNS 3.x. Big thanks to @MattNer0, @sitefinitysteve, @hristo, @NickIliev
• Fixed the "refresh observable" issue on Android, thanks @MattNer0.
• New property to enable/disable scroll, thanks @sitefinitysteve.
• New property for Android: indicatorOffset, thanks @sitefinitysteve.
• Fixed issue with orientation change on iOS. Please use nativescript-orientation plugin in order to trigger UI-refresh.
• Code refactor & cleanup, introduced common.js
• Updated Pod & Android-IndicatorView to latest version.

2.4.2

• Added bounce property to the plugin and the Pod. Thanks to @sitefinitysteve.

2.4.1

• Fixed an issue on iOS when updating Items binding, would not refresh Carousel-view.

2.4.0

• Added new event, 'pageScrolling'. Thanks to @sitefinitysteve!
• Updated gradle for 'PageIndicatorView' to version 0.1.2
• Updated package.json with 'plugin' metadata to comply with the upcomming 3.0 plugin standard
• Potential fix for ViewPager.populate exception on Android.

2.3.1

• Potential fix for ng2 & webpack users (Trying to link invalid 'this' to a Java object). Thanks @peterstaev.
• Updated android indicators gradle plugin. New animation: swap!

2.3.0

• Changed the iOS Pod to point to our own repo! We have the control ;)
• New property available for iOS: indicatorColorUnselected. Allows you to set color to the unselected dots.

2.2.0

• Fixed issue with the refresh function that could cause a crash or removal of slides (Android).
• Updated Android-indicators gradle library to v0.1.0. More stable and more animations! New animations are: drop, scale and thin_worm.
• Fixed issue with a small white bar being shown if the indicators are disabled (Android). Thanks to @EddyVerbruggen.
• Fixed, another, potential bug that would cause app to crash when resuming he activity (Android).

2.1.2

• Fixed a critical bug that would cause the app to crash when resuming the activity (Android). Thanks to @EddyVerbruggen.

2.1.1

• Corrected README, iOS does indeed allow for tap-events innside the CarouselItems. Thanks @terreb!
• Fixed the selectedPage property on iOS, now also returns selected index.
• Updated iOS Podfile to 1.4.12

2.1.0

• Added Android support!
• Android gets animated pager-indicators made by @romandanylyk.

1.1.0

• Updated pod with version '1.4.10'
• Fixed page-change-event when finite is set to 'true'
• Added new property 'selectedPage' (set active page by index).
• Updated demo app

1.0.0

• Initial release

Author

• manijak

Collaborators

• bradmartin
• sitefinitysteve
• EddyVerbruggen
• Pip3r4o
• MattNer0

Contributing

I will accept pull requests that improve this and assign credit.

• Fork and clone the repository
• cd src && npm run setup
• npm run demo.android for android development
• npm run demo.ios for iOS development
• npm run demo-ng.ios for iOS Angular app
• npm run demo-ng.android for Android Angular
• npm run demo-vue.ios for iOS Vue app
• npm run demo-vue.android for Android Vue