ons-carousel

Carousel component.

Carousel component. A carousel can be used to display several items in the same space. The component supports displaying content both horizontally and vertically. The user can scroll through the items by dragging and it can also be controller programmatically.

Tutorial

A carousel is a UI component that is used to display several items in the same place. Switching between the content can either be automatic or controlled by the user.

In Onsen UI a carousel is created using the <ons-carousel> element.

<ons-carousel>
  <ons-carousel-item>
    ...
  </ons-carousel-item>
  <ons-carousel-item>
    ...
  </ons-carousel-item>
  ...
</ons-carousel>

Customization

The <ons-carousel> element has a large number of attributes that control its behavior.

By default the carousel can not be controlled by swiping. The swipeable attribute will enabled this.

To make it automatically snap to item borders the auto-scroll attribute is used. The overscrollable attribute makes it possible to scroll past the first and last element of the carousel.

To make it cover the whole screen you can use the fullscreen attribute.

Changing the direction

The carousel goes from left to right by default. It is possible to make scroll vertically by using the direction attribute.

<ons-carousel direction="vertical">
  ...
</ons-carousel>

You can try adding the direction="vertical" attribute to this example to see how it works.

Methods

The carousel can also be controlled programmatically. To switch to the previous or next item the prev() and next() are used.

To switch to a specific item the setActiveIndex(index) method is used.

Events

The carousel element emits DOM event. Every time the current item has changed it emits the postchange event which is useful to make sure which is the currently displayed item.

In AngularJS this event can be handled in ons-postchange attribute:

<ons-carousel ons-postchange="console.log('Changed to ' + $event.activeIndex)"></ons-carousel>

See also

Attributes

Name Type Default Value Description
String The direction of the carousel. Can be either “horizontal” or “vertical”. Default is “horizontal”. Optional.
If this attribute is set the carousel will cover the whole screen. Optional.
If this attribute is set the carousel will be scrollable over the edge. It will bounce back when released. Optional.
If this attribute is set the carousel then the selected item will be in the center of the carousel instead of the beginning. Useful only when the items are smaller than the carousel. Optional.
String ons-carousel-item’s width. Only works when the direction is set to “horizontal”. Optional.
String ons-carousel-item’s height. Only works when the direction is set to “vertical”. Optional.
If this attribute is set the carousel will be automatically scrolled to the closest item border when released. Optional.
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.
If this attribute is set the carousel can be scrolled by drag or swipe. Optional.
If this attribute is set the carousel is disabled. Optional.
Number
0
Specify the index of the ons-carousel-item to show initially. Default is 0. Optional. Works only during initialization.
When this attribute is set the carousel will automatically refresh when the number of child nodes change. Optional.
String If this attribute is set to "none" the transitions will not be animated. Optional.
Expression Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}. Optional.
String Variable name to refer this carousel. Optional. Works only during initialization.
Expression Allows you to specify custom behavior when the “postchange” event is fired. Optional. Works only during initialization.
Expression Allows you to specify custom behavior when the “refresh” event is fired. Optional. Works only during initialization.
Expression Allows you to specify custom behavior when the “overscroll” event is fired. Optional. Works only during initialization.
Expression Allows you to specify custom behavior when the “destroy” event is fired. Optional. Works only during initialization.

Properties

Name Description
itemCount The number of carousel items.
swipeable true if the carousel is swipeable.
onSwipe Hook called whenever the user slides the carousel. It gets a decimal index and an animationOptions object as arguments.
autoScroll true if auto scroll is enabled.
autoScrollRatio The current auto scroll ratio.
disabled Whether the carousel is disabled or not.
overscrollable Whether the carousel is overscrollable or not.
centered Whether the carousel is centered or not.

Methods Summary

Signature Description
setActiveIndex(index, [options]) Specify the index of the <ons-carousel-item> to show.
getActiveIndex() Returns the index of the currently visible <ons-carousel-item>.
next([options]) Show next <ons-carousel-item>.
prev([options]) Show previous <ons-carousel-item>.
first() Show first <ons-carousel-item>.
last() Show last ons-carousel item.
refresh() Update the layout of the carousel. Used when adding <ons-carousel-items> dynamically or to automatically adjust the size.
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.
on(eventName, listener) Add an event listener.

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

setActiveIndex(index, [options]): Promise

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

Returns: Resolves to the carousel element.

Parameters
Name Type Description
index Number The index that the carousel should be set to.
options Object Parameter object.
options.callback Function A function that will be called after the animation is finished.
options.animation String If this attribute is set to "none" the transitions will not be animated.
options.animationOptions Object An object that can be used to specify duration, delay and timing function of the animation.

getActiveIndex(): Number

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

Returns: The current carousel item index.

next([options]): Promise

Show next <ons-carousel-item>.

Returns: Resolves to the carousel element

Parameters
Name Type Description
options Object Parameter object.
options.callback Function A function that will be executed after the animation has finished.
options.animation String If this attribute is set to "none" the transitions will not be animated.
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation.

prev([options]): Promise

Show previous <ons-carousel-item>.

Returns: Resolves to the carousel element

Parameters
Name Type Description
options Object Parameter object.
options.callback Function A function that will be executed after the animation has finished.
options.animation String If this attribute is set to "none" the transitions will not be animated.
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation.

first(): Promise

Show first <ons-carousel-item>.

Returns: Resolves to the carousel element

Parameters
Name Type Description
options Object Parameter object.
options.callback Function A function that will be executed after the animation has finished.
options.animation String If this is set to "none", the transitions will not be animated.
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation.

last(): Promise

Show last ons-carousel item.

Returns: Resolves to the carousel element

Parameters
Name Type Description
options Object Parameter object.
options.callback Function A function that will be executed after the animation has finished.
options.animation String If this attribute is set to "none" the transitions will not be animated.
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation.

refresh()

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

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.

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.

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

Need Help?

If you have any questions, use our Community Forum or talk to us via Gitter chat. The Onsen UI team and your peers in the community will work together to help solve your issues.

For bug reports and feature requests use our GitHub Issues page.