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.
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>
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. If the carousel is not fullscreen you may need to specify the height or the width of the items through CSS.
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.
<ons-carousel> element slightly modifies its content to make it swipeable by adding div.ons-swiper-target wrapper. The final results look like this:
<ons-carousel>
<div class="ons-swiper-target">
<ons-carousel-item></ons-carousel-item>
<ons-carousel-item></ons-carousel-item>
<ons-carousel-item></ons-carousel-item>
</div>
</ons-carousel>
This wrapper can also be manually provided.
Attributes are added directly to the element. You can do this in HTML or JS.
HTML: <ons-carousel someAttribute="true" anotherAttribute><ons-carousel>
JS: document.querySelector('ons-carousel').setAttribute('someAttribute', 'true')
| Name | Type | 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. | |
| overscrollable | If this attribute is set the carousel will be scrollable over the edge. It will bounce back when released. Optional. | |
| centered | 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. | |
| 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. | |
| initial-index |
Number
0 |
Specify the index of the ons-carousel-item to show initially. Default is 0. If active-index is set, initial-index is ignored. Optional. Works only during initialization. |
| auto-refresh | When this attribute is set the carousel will automatically refresh when the number of child nodes change. Optional. | |
| animation | String |
If this attribute is set to "none" the transitions will not be animated.
Optional.
|
| animation-options | Expression |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
Optional.
|
| active-index | Number | Specify the index of the carousel item that should be shown. Optional. |
Properties are accessed on the element through JS, and should be get and set directly. For example: document.querySelector('ons-carousel').fullscreen.
| Name | Description |
|---|---|
| fullscreen | If this property is set the carousel will cover the whole screen. |
| autoRefresh | When this property is set the carousel will automatically refresh when the number of child nodes change. |
| 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. |
| animationOptions |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
|
| activeIndex | Specify the index of the carousel item that should be shown. |
These methods are called directly on the DOM element. Get a reference to the element in JS, and the methods below will be available to call on it. For example: document.querySelector('ons-carousel').someMethod().
| 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.
|
Specify the index of the <ons-carousel-item> to show.
Returns: Resolves to the carousel element.
| 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. |
Returns the index of the currently visible <ons-carousel-item>.
Returns: The current carousel item index.
Show next <ons-carousel-item>.
Returns: Resolves to the carousel element
| 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. |
Show previous <ons-carousel-item>.
Returns: Resolves to the carousel element
| 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. |
Show first <ons-carousel-item>.
Returns: Resolves to the carousel element
| 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. |
Show last ons-carousel item.
Returns: Resolves to the carousel element
| 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. |
Update the layout of the carousel. Used when adding <ons-carousel-items> dynamically or to automatically adjust the size.
To use these events, add event listeners to the elements as you would for native events, like click. For example: document.querySelector('ons-carousel').addEventListener('postchange', function() { ... }).
Some Onsen UI components have overlapping event names. For example, ons-carousel and ons-navigator both emit postchange events. Stop overlapping events from propagating to avoid conflicts: document.querySelector('ons-carousel').on('postchange', e => e.stopPropagation()).
| Name | Description |
|---|---|
| postchange | Fired just after the current carousel item has changed. |
| prechange | Fired just before the current carousel item changes. |
| refresh | Fired when the carousel has been refreshed. |
| overscroll | Fired when the carousel has been overscrolled. |
| swipe | Fires when the carousel swipes. |
Fired just after the current carousel item has changed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.carousel | Object | Carousel object. |
| event.activeIndex | Number | Current active index. |
| event.lastActiveIndex | Number | Previous active index. |
Fired just before the current carousel item changes.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.carousel | Object | Carousel object. |
| event.activeIndex | Number | Current active index. |
| event.lastActiveIndex | Number | Previous active index. |
Fired when the carousel has been refreshed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.carousel | Object | Carousel object. |
Fired when the carousel has been overscrolled.
| 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.
|
Fires when the carousel swipes.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.index | Number | Current index. |
| event.options | Object | Animation options object. |
If you have any questions, use our Community Forum or talk to us on Discord 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.