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

NativeScript 7+:

ns plugin add nativescript-carousel

NativeScript less than NS7:

tns plugin add nativescript-carousel@6.1.1

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

7.0.1

• Hotfix release: Fixes issues with the @NativeClass() decorator.

7.0.0

• Plugin updated to support NativeScript v7.0 release. Thanks to @BradMartin, @NathanWalker & @rickwalking for all the PRs and making sure the code compiles & runs. 👏

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
• NathanWalker
• rickwalking
• 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