• Guide
    • Onsen UI Overview
    • Using with Frameworks
    • jQuery
    • AngularJS 1.x
    • Angular 2+
    • React
    • Vue.js 2
    • Vue.js 3
    • Onsen UI 1.x
  • API
    • CSS Components
    • JavaScript (Web Components)
    • AngularJS 1.x
    • Angular 2+
    • React
    • Vue.js 2
    • Vue.js 3
    • Onsen UI 1.x
  • Components
  • Resources
    • Theme Roller
    • Samples
    • Playground
    • Community
    • Blog
    • Awesome Onsen UI
  • NEWS
    RECENT ACTIVITIES
    Loading...
View Source Improve this doc

ons-carousel

Carousel component.

  • Usage
  • Live Example
  • Attributes
  • Methods
  • Events
  • See Also
  • Discussion

Usage #

<ons-carousel style="width: 100%; height: 200px">
  <ons-carousel-item>
   ...
  </ons-carousel-item>
  <ons-carousel-item>
   ...
  </ons-carousel-item>
</ons-carousel>

Live Example #

See the Pen Alert, confirm and prompt dialogs by Onsen & Monaca (@onsen) on CodePen.

Open in New Window

See also #

  • Learn how to use the carousel component.

Attributes #

Name Type
Default Value
Description
direction String The direction of the carousel. Can be either "horizontal" or "vertical". Default is "horizontal". Optional
fullscreen If this attribute is set the carousel will cover the whole screen. Optional
var String Variable name to refer this carousel. Optional
overscrollable If this attribute is set the carousel will be scrollable over the edge. It will bounce back when released. Optional
item-width String ons-carousel-item's width. Only works when the direction is set to "horizontal". Optional
item-height String ons-carousel-item's height. Only works when the direction is set to "vertical". Optional
auto-scroll If this attribute is set the carousel will be automatically scrolled to the closest item border when released. Optional
auto-scroll-ratio Number A number between 0.0 and 1.0 that specifies how much the user must drag the carousel in order for it to auto scroll to the next item. Optional
swipeable If this attribute is set the carousel can be scrolled by drag or swipe. Optional
disabled If this attribute is set the carousel is disabled. Optional
intial-index Number Specify the index of the ons-carousel-item to show initially. Default is 0. Optional
auto-refresh When this attribute is set the carousel will automatically refresh when the number of child nodes change. Optional
ons-postchange Expression Allows you to specify custom behavior when the "postchange" event is fired. Optional
ons-refresh Expression Allows you to specify custom behavior when the "refresh" event is fired. Optional
ons-overscroll Expression Allows you to specify custom behavior when the "overscroll" event is fired. Optional
ons-destroy Expression Allows you to specify custom behavior when the "destroy" event is fired. Optional

Methods Summary #

Signature Description
next() Show next ons-carousel item.
prev() Show previous ons-carousel item.
first() Show first ons-carousel item.
last() Show last ons-carousel item.
setSwipeable(swipeable) Set whether the carousel is swipeable or not.
isSwipeable() Returns whether the carousel is swipeable or not.
setActiveCarouselItemIndex(index) Specify the index of the ons-carousel-item to show.
getActiveCarouselItemIndex() Returns the index of the currently visible ons-carousel-item.
setAutoScrollEnabled(enabled) Enable or disable "auto-scroll" attribute.
isAutoScrollEnabled() Returns whether the "auto-scroll" attribute is set or not.
setAutoScrollRatio(ratio) Set the auto scroll ratio. Must be a value between 0.0 and 1.0.
getAutoScrollRatio() Returns the current auto scroll ratio.
setOverscrollable(overscrollable) Set whether the carousel is overscrollable or not.
isOverscrollable() Returns whether the carousel is overscrollable or not.
refresh() Update the layout of the carousel. Used when adding ons-carousel-items dynamically or to automatically adjust the size.
isDisabled() Returns whether the dialog is disabled or enabled.
setDisabled(disabled) Disable or enable the dialog.
on(eventName, listener) Add an event listener.
once(eventName, listener) Add an event listener that's only triggered once.
off(eventName, [listener]) Remove an event listener. If the listener is not specified all listeners for the event type will be removed.

Events Summary #

Name Description
postchange Fired just after the current carousel item has changed.
refresh Fired when the carousel has been refreshed.
overscroll Fired when the carousel has been overscrolled.

Methods

next() #

Show next ons-carousel item.

prev() #

Show previous ons-carousel item.

first() #

Show first ons-carousel item.

last() #

Show last ons-carousel item.

setSwipeable(swipeable) #

Set whether the carousel is swipeable or not.

Parameters
Name Type Description
swipeable Booelan If value is true the carousel will be swipeable.

isSwipeable(): Boolean #

Returns whether the carousel is swipeable or not.

Returns: true if the carousel is swipeable.

setActiveCarouselItemIndex(index) #

Specify the index of the ons-carousel-item to show.

Parameters
Name Type Description
index Number The index that the carousel should be set to.

getActiveCarouselItemIndex(): Number #

Returns the index of the currently visible ons-carousel-item.

Returns: The current carousel item index.

setAutoScrollEnabled(enabled) #

Enable or disable "auto-scroll" attribute.

Parameters
Name Type Description
enabled Boolean If true auto scroll will be enabled.

isAutoScrollEnabled(): Boolean #

Returns whether the "auto-scroll" attribute is set or not.

Returns: true if auto scroll is enabled.

setAutoScrollRatio(ratio) #

Set the auto scroll ratio. Must be a value between 0.0 and 1.0.

Parameters
Name Type Description
ratio Number The desired ratio.

getAutoScrollRatio(): Number #

Returns the current auto scroll ratio.

Returns: The current auto scroll ratio.

setOverscrollable(overscrollable) #

Set whether the carousel is overscrollable or not.

Parameters
Name Type Description
overscrollable Boolean If true the carousel will be overscrollable.

isOverscrollable(): Boolean #

Returns whether the carousel is overscrollable or not.

Returns: Whether the carousel is overscrollable or not.

refresh() #

Update the layout of the carousel. Used when adding ons-carousel-items dynamically or to automatically adjust the size.

isDisabled(): Boolean #

Returns whether the dialog is disabled or enabled.

Returns: Whether the carousel is disabled or not.

setDisabled(disabled) #

Disable or enable the dialog.

Parameters
Name Type Description
disabled Boolean If true the carousel will be disabled.

on(eventName, listener) #

Add an event listener.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.

once(eventName, listener) #

Add an event listener that's only triggered once.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.

off(eventName, [listener]) #

Remove an event listener. If the listener is not specified all listeners for the event type will be removed.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.

Events

postchange #

Fired just after the current carousel item has changed.

Parameters
Name Type Description
event Object Event object.
event.carousel Object Carousel object.
event.activeIndex Number Current active index.
event.lastActiveIndex Number Previous active index.

refresh #

Fired when the carousel has been refreshed.

Parameters
Name Type Description
event Object Event object.
event.carousel Object Carousel object.

overscroll #

Fired when the carousel has been overscrolled.

Parameters
Name Type Description
event Object Event object.
event.carousel Object Fired when the carousel has been refreshed.
event.activeIndex Number Current active index.
event.direction String Can be one of either "up", "down", "left" or "right".
event.waitToReturn Function Takes a Promise object as an argument. The carousel will not scroll back until the promise has been resolved or rejected.

Discussion #

Stay up to date!

Get updates on Onsen UI, Monaca and hybrid app development. No more than 2-3 times a month.


Thanks for subscribing!