Carousel widget
The Carousel Widget allows you to create and render carousels, enabling the presentation of multiple items in a visually engaging and interactive slideshow format within your application.
Test in Kitchen Sink (opens in a new tab)
Properties
| Property | Type | Description |
|---|---|---|
| children | array | List of widgets |
| onItemChange | action | Dispatch when an carousel item is in focus. For SingleView, this happens when the item is scroll into view. For scrolling MultiView, the event dispatches only when you tap on the item. The index of the item can be retrieved using 'selectedIndex'. |
| item-template | object | See properties |
Styles
| Property | Type | Description |
|---|---|---|
| layout | string | Show a SingleView (on screen one at a time), MultiView (scrolling items), or automatically switch between the views with autoLayoutBreakpoint |
| autoLayoutBreakpoint | integer | Show multiple views on the carousel if the breakpoint is equal or larger than this threshold, otherwise show single view. (default 768) |
| autoplay | boolean | If true, Enables autoplay, sliding one page at a time. Default (false) |
| autoplayInterval | integer | Sets the duration in seconds for the autoplay. Default (4 second) |
| height | integer | The height of each view |
| gap | integer | The gap between each views, but also act as a left-right margin in a single view |
| leadingGap | integer | The space before the first item. Note that the left edge of the scroll area is still controlled by padding or margin. |
| trailingGap | integer | The space after the last item. Note that the right edge of the scroll area is still controlled by padding or margin. |
| singleItemWidthRatio | number | The screen width ratio for each carousel item (in single item mode). Value ranges from 0.0 to 1.0 for the full width. (default 1.0) |
| multipleItemWidthRatio | number | The screen width ratio for each carousel item (in multiple item mode). Value ranges from 0.0 to 1.0 for the full width (default 0.6) |
| indicatorType | string | How the view indicator should be displayed |
| indicatorPosition | string | Where to display the indicator if specified |
| indicatorWidth | integer | Sets the width of the carousel indicators within the Carousel |
| indicatorHeight | integer | Adjusts the height of the carousel indicators within the Carousel |
| indicatorMargin | string or integer | The margin around each indicator |
| indicatorPadding | string or integer | The padding around the indicator |
| aspectRatio | number | Aspect ratio is used if no height have been declared. |
| autoPlayAnimationDuration | integer | The animation duration between two transitioning pages while in auto playback. |
| autoPlayCurve | string | Determines the animation curve physics. |
| enlargeCenterPage | boolean | Determines if current page should be larger than the side images, creating a feeling of depth in the carousel. |
| enlargeFactor | number | How much the pages next to the center page will be scaled down. If enlargeCenterPage is false, this property has no effect. |
| direction | string | The axis along which the carousel view scrolls. |
| cacheKey | string | Pass a cacheKey if you want to keep the carousel's item position when it was recreated |
| buildOnDemand | boolean | Build the carousel items only when its visible in the screen. Default - false |
| buildOnDemandLength | integer | Build the carousel items when its visible in the screen only when the item is greater or equal to this length. Default - 6 |
Box Styles (Inherited)
This widget also inherits these styles
| Property | Type | Description |
|---|---|---|
| margin | integer/string | Margin with CSS-style notation (1 to 4 integers) e.g. margin: 5 20 5 |
| padding | integer/string | Padding with CSS-style notation (1 to 4 integers) e.g. padding: 5 20 5 |
| backgroundColor | Color | The background color of this widget. |
| backgroundImage | BackgroundImage | The background image of this widget. |
| backgroundGradient | Gradient | The background gradient of this widget. |
| border | Border | The border of this widget. |
| shadow | Shadow | The shadow of this widget |
| clipContent | boolean | Some widgets (such as Image) may bleed through the container when borderRadius is set. Use this to apply a clipping to ensure this does not happen. |
| width | integer | The width of this widget. |
| height | integer | The height of this widget. |
| borderRadius | string or integer | The border radius of the widget. This can be specified using CSS-like notation with 1 to 4 integers. Minimum value: 0. |
| borderColor | integer or string | Sets the border color, starting with '0xFF' for full opacity. Possible values: transparent, black, blue, white, red, grey, teal, amber, pink, purple, yellow, green, brown, cyan, indigo, lime, orange. |
| borderWidth | integer | Thickness of the border. Minimum value should be 0. |
| shadowColor | integer or string | Sets the box shadow color starting with '0xFF' for full opacity. Possible values: transparent, black, blue, white, red, grey, teal, amber, pink, purple, yellow, green, brown, cyan, indigo, lime, orange. |
| shadowOffset | array | The values in the array define the horizontal and vertical offset of the shadow. Example: if the shadowOffset is set to [2, 4], the shadow will be offset by 2 pixels horizontally and 4 pixels vertically from its original position. |
| shadowRadius | string or integer | The border radius of the widget. This can be specified using CSS-like notation with 1 to 4 integers. Minimum value: 0. |
| shadowStyle | string | The blur style to apply on the shadow: normal, solid, outer, inner. |
Base Styles (Inherited)
This widget also inherits these styles
| Property | Type | Description |
|---|---|---|
| visible | boolean | Toggle a widget visibility on/off. Note that an invisible widget will not occupy UI space, unless the visibilityTransitionDuration is specified. |
| visibilityTransitionDuration | number | Specify the duration in seconds when a widget animates between visible and not visible state. Note that setting this value will cause the widget to still occupy the UI space even when it is not visible. |
| elevation | integer | The z-coordinate at which to place this material relative to its parent. A non-zero value will show a shadow, with its size relative to the elevation value. (Minimum: 0, Maximum: 24) |
| elevationShadowColor | Color | The shadow color for the elevation. |
| elevationBorderRadius | integer / string | If the widget has a borderRadius, this should be changed to have the same value. Use with CSS-like notation (1 to 4 integers). |
| alignment | Alignment | Align this widget relative to its parent. |
| stackPositionTop | integer | The distance of the child's top edge from the top of the stack. This is applicable only for Stack's children. |
| stackPositionBottom | integer | The distance that the child's bottom edge from the bottom of the stack. This is applicable only for Stack's children. |
| stackPositionLeft | integer | The distance that the child's left edge from the left of the stack. This is applicable only for Stack's children. |
| stackPositionRight | integer | The distance that the child's right edge from the right of the stack. This is applicable only for Stack's children. |
| captureWebPointer | boolean | Applicable for Web only. When overlaying widgets on top of certain HTML container (e.g., Maps), the mouse click is captured by the HTML container, causing issue interacting with the widget. Use this to capture and maintain the mouse pointer on your widget. |
item-template
| Property | Type | Description |
|---|---|---|
| data | string | Bind to an array of data from an API response or a variable |
| name | string | Set the name to reference as you iterate through the array of data |
| template | widget | The widget to render for each item |