Carousel JAVASCRIPT UI Component API

Carousel Javascript API

Class

Carousel

Carousel is a slideshow component for cycling through elements—images or slides of text

smart-carousel

Properties

AanimationSets or gets the animation mode. Animation is disabled when the property is set to 'none'
AautoPlayThe items switch automatically if set to true or to a custom number(representing the timeout in milliseconds). This property works if slideShow property is enabled.
DdataSourceAn array of objects. Each object defines an item. The following object properties are available: label - a string representing the label of the item.content - a string representing the content of the itemimage - a string representing a url link to an image.HTMLcontent - a string representing some HTML structure taht will be generated inside the item.
DdelaySpecifies the timeout before a slide changes when a navigation button is pressed. Navigation buttons are repeat buttons that will repeat the oepration after the delay is passed.
DdisabledEnables or disables the element.
DdisableItemClickDisabled the possibility to navigated to an item by clicking on item in displayMode 3d. By default users can navigate to items that are not currently active by clicking on them.
DdisplayModeDetermines the display mode.
HhideArrowsHides the navigation buttons.
HhideIndicatorsHides the slide indication panel that shows which item is currently in view (active item).
IindicatorTemplateCan be used to customize the slide indicator panel of the accordion. The property can be a string that represents the id of an HTMLTemplateElement in the DOM or it's direct reference.
IintervalDetermines the interval (in milliseconds) between a slide transitions when slideShow is enabled.
IitemTemplateUsed to completely customize the content of an item. The property can be a string that represents the id of an HTMLTemplateElement in the DOM or it's direct reference. The content of the template can contain property bindings that refer to the dataSource.
KkeyboardActivates/deactivates keyboard navigation. By default, items can not be navigated via keyboard
LlocaleSets or gets the language. Used in conjunction with the property messages.
LlocalizeFormatFunctionCallback used to customize the format of the messages that are returned from the Localization Module.
LloopDetermines whether the the items should start over when the first or last item is reached.
MmessagesSets or gets an object specifying strings used in the widget that can be localized. Used in conjunction with the property locale.
RreadonlyIf the element is readonly, users cannot interact with it.
RrightToLeftSets or gets the value indicating whether the element is aligned to support locales using right-to-left fonts.
SslideShowWhen slideShow property is set to true, the carousel changes the active slide automatically with a delay set in interval property.
SswipeEnables or disables switching to the previous/next slide via swiping left/right. By default swiping is disabled.
TthemeDetermines the theme. Theme defines the look of the element
UunfocusableIf is set to true, the element cannot be focused.
WwheelActivates/deactivates slide navigation via mouse wheel. By default it's disabled.

Events

CchangeTriggered when the active ( in view ) slide is changed.
CchangingTriggered when the process of slide changing starts.
SswipeleftThis event is triggered when the user swipes to the left inside the Carousel.
SswiperightThis event is triggered when the user swipes to the right inside the Carousel.

Methods

NnextNavigates to the next slide.
PpausePauses the slide show if slideShow is enabled.
PplayStarts the slide show if slideShow is enabled.
PprevNavigates to the previous slide.
SslideToNavigates to a specific slide with the given index.

animation"none" | "simple" | "advanced"

Sets or gets the animation mode. Animation is disabled when the property is set to 'none'

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Example

Set the animation property. 

 <smart-carousel animation='none'></smart-carousel>

Set the animation property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.animation = 'simple';

Get the animation property. 

 const carousel = document.querySelector('smart-carousel');
 let animation = carousel.animation;

autoPlayboolean

The items switch automatically if set to true or to a custom number(representing the timeout in milliseconds). This property works if slideShow property is enabled.

Default value

false
Try a demo showcasing the autoPlay property.

Example

Set the autoPlay property. 

 <smart-carousel auto-play></smart-carousel>

Set the autoPlay property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.autoPlay = 500;

Get the autoPlay property. 

 const carousel = document.querySelector('smart-carousel');
 let autoPlay = carousel.autoPlay;

dataSource[]

An array of objects. Each object defines an item. The following object properties are available:

  • label - a string representing the label of the item.
  • content - a string representing the content of the item
  • image - a string representing a url link to an image.
  • HTMLcontent - a string representing some HTML structure taht will be generated inside the item.

Try a demo showcasing the dataSource property.

Example

Set the dataSource property. 

 <smart-carousel data-source='[{ label: 'Slide 1', content: 'Some content'}, { label: 'Slide 2', image: '../../images/carousel-medium-1.jpg'}, { label: 'Slide 3'}]'></smart-carousel>

Set the dataSource property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.dataSource = [{ label: 'Slide 1', content: 'Content 1'}, { label: 'Slide 2', content: 'Content 2'}, { label: 'Slide 3', content: 'Content 3'}];

Get the dataSource property. 

 const carousel = document.querySelector('smart-carousel');
 let dataSource = carousel.dataSource;

delaynumber

Specifies the timeout before a slide changes when a navigation button is pressed. Navigation buttons are repeat buttons that will repeat the oepration after the delay is passed.

Default value

200

Example

Set the delay property. 

 <smart-carousel delay='1000'></smart-carousel>

Set the delay property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.delay = 2000;

Get the delay property. 

 const carousel = document.querySelector('smart-carousel');
 let delay = carousel.delay;

disabledboolean

Enables or disables the element.

Default value

false

Example

Set the disabled property. 

 <smart-carousel disabled></smart-carousel>

Set the disabled property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.disabled = false;

Get the disabled property. 

 const carousel = document.querySelector('smart-carousel');
 let disabled = carousel.disabled;

disableItemClickboolean

Disabled the possibility to navigated to an item by clicking on item in displayMode 3d. By default users can navigate to items that are not currently active by clicking on them.

Default value

false

Example

Set the disableItemClick property. 

 <smart-carousel disable-item-click></smart-carousel>

Set the disableItemClick property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.disableItemClick = false;

Get the disableItemClick property. 

 const carousel = document.querySelector('smart-carousel');
 let disableItemClick = carousel.disableItemClick;

displayMode"default" | "multiple" | "3d"

Determines the display mode.

Allowed Values

  • "default" - The items are presented as 2D slides.
  • "multiple" - Multiple items are presented on each slide as 2D slides.
  • "3d" - Items are displayed in 3D perspective where each item has it's own slide.

Default value

"default"

Example

Set the displayMode property. 

 <smart-carousel display-mode='multiple'></smart-carousel>

Set the displayMode property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.displayMode = '3d';

Get the displayMode property. 

 const carousel = document.querySelector('smart-carousel');
 let displayMode = carousel.displayMode;

hideArrowsboolean

Hides the navigation buttons.

Default value

false
Try a demo showcasing the hideArrows property.

Example

Set the hideArrows property. 

 <smart-carousel hide-arrows></smart-carousel>

Set the hideArrows property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.hideArrows = false;

Get the hideArrows property. 

 const carousel = document.querySelector('smart-carousel');
 let hideArrows = carousel.hideArrows;

hideIndicatorsboolean

Hides the slide indication panel that shows which item is currently in view (active item).

Default value

false
Try a demo showcasing the hideIndicators property.

Example

Set the hideIndicators property. 

 <smart-carousel hide-indicators></smart-carousel>

Set the hideIndicators property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.hideIndicators = false;

Get the hideIndicators property. 

 const carousel = document.querySelector('smart-carousel');
 let hideIndicators = carousel.hideIndicators;

indicatorTemplateany

Can be used to customize the slide indicator panel of the accordion. The property can be a string that represents the id of an HTMLTemplateElement in the DOM or it's direct reference.

Try a demo showcasing the indicatorTemplate property.

Example

Set the indicatorTemplate property. 

 <smart-carousel indicator-template='templateId1'></smart-carousel>

Set the indicatorTemplate property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.indicatorTemplate = templateId2;

Get the indicatorTemplate property. 

 const carousel = document.querySelector('smart-carousel');
 let indicatorTemplate = carousel.indicatorTemplate;

intervalnumber

Determines the interval (in milliseconds) between a slide transitions when slideShow is enabled.

Default value

5000
Try a demo showcasing the interval property.

Example

Set the interval property. 

 <smart-carousel interval='1000'></smart-carousel>

Set the interval property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.interval = 2000;

Get the interval property. 

 const carousel = document.querySelector('smart-carousel');
 let interval = carousel.interval;

itemTemplateany

Used to completely customize the content of an item. The property can be a string that represents the id of an HTMLTemplateElement in the DOM or it's direct reference. The content of the template can contain property bindings that refer to the dataSource.

Try a demo showcasing the itemTemplate property.

Example

Set the itemTemplate property. 

 <smart-carousel item-template='templateId1'></smart-carousel>

Set the itemTemplate property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.itemTemplate = templateId2;

Get the itemTemplate property. 

 const carousel = document.querySelector('smart-carousel');
 let itemTemplate = carousel.itemTemplate;

keyboardboolean

Activates/deactivates keyboard navigation. By default, items can not be navigated via keyboard

Default value

false
Try a demo showcasing the keyboard property.

Example

Set the keyboard property. 

 <smart-carousel keyboard></smart-carousel>

Set the keyboard property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.keyboard = false;

Get the keyboard property. 

 const carousel = document.querySelector('smart-carousel');
 let keyboard = carousel.keyboard;

localestring

Sets or gets the language. Used in conjunction with the property messages.

Default value

"en"

Example

Set the locale property. 

 <smart-carousel locale='de'></smart-carousel>

Set the locale property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.locale = 'fr';

Get the locale property. 

 const carousel = document.querySelector('smart-carousel');
 let locale = carousel.locale;

localizeFormatFunctionfunction | null

Callback used to customize the format of the messages that are returned from the Localization Module.

Example

Set the localizeFormatFunction property. 

 <smart-carousel localize-format-function='function(defaultMessage, message, messageArguments){return '...'}'></smart-carousel>

Set the localizeFormatFunction property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property. 

 const carousel = document.querySelector('smart-carousel');
 let localizeFormatFunction = carousel.localizeFormatFunction;

loopboolean

Determines whether the the items should start over when the first or last item is reached.

Default value

false
Try a demo showcasing the loop property.

Example

Set the loop property. 

 <smart-carousel loop></smart-carousel>

Set the loop property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.loop = false;

Get the loop property. 

 const carousel = document.querySelector('smart-carousel');
 let loop = carousel.loop;

messagesobject

Sets or gets an object specifying strings used in the widget that can be localized. Used in conjunction with the property locale.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Example

Set the messages property. 

 <smart-carousel messages='{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss."}}'></smart-carousel>

Set the messages property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}:  Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Get the messages property. 

 const carousel = document.querySelector('smart-carousel');
 let messages = carousel.messages;

readonlyboolean

If the element is readonly, users cannot interact with it.

Default value

false

Example

Set the readonly property. 

 <smart-carousel readonly></smart-carousel>

Set the readonly property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.readonly = true;

Get the readonly property. 

 const carousel = document.querySelector('smart-carousel');
 let readonly = carousel.readonly;

rightToLeftboolean

Sets or gets the value indicating whether the element is aligned to support locales using right-to-left fonts.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-carousel right-to-left></smart-carousel>

Set the rightToLeft property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.rightToLeft = true;

Get the rightToLeft property. 

 const carousel = document.querySelector('smart-carousel');
 let rightToLeft = carousel.rightToLeft;

slideShowboolean

When slideShow property is set to true, the carousel changes the active slide automatically with a delay set in interval property.

Default value

false
Try a demo showcasing the slideShow property.

Example

Set the slideShow property. 

 <smart-carousel slide-show></smart-carousel>

Set the slideShow property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.slideShow = false;

Get the slideShow property. 

 const carousel = document.querySelector('smart-carousel');
 let slideShow = carousel.slideShow;

swipeboolean

Enables or disables switching to the previous/next slide via swiping left/right. By default swiping is disabled.

Default value

false
Try a demo showcasing the swipe property.

Example

Set the swipe property. 

 <smart-carousel swipe></smart-carousel>

Set the swipe property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.swipe = false;

Get the swipe property. 

 const carousel = document.querySelector('smart-carousel');
 let swipe = carousel.swipe;

themestring

Determines the theme. Theme defines the look of the element

Default value

""

Example

Set the theme property. 

 <smart-carousel theme='blue'></smart-carousel>

Set the theme property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.theme = 'red';

Get the theme property. 

 const carousel = document.querySelector('smart-carousel');
 let theme = carousel.theme;

unfocusableboolean

If is set to true, the element cannot be focused.

Default value

false

Example

Set the unfocusable property. 

 <smart-carousel unfocusable></smart-carousel>

Set the unfocusable property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.unfocusable = false;

Get the unfocusable property. 

 const carousel = document.querySelector('smart-carousel');
 let unfocusable = carousel.unfocusable;

wheelboolean

Activates/deactivates slide navigation via mouse wheel. By default it's disabled.

Default value

false
Try a demo showcasing the wheel property.

Example

Set the wheel property. 

 <smart-carousel wheel></smart-carousel>

Set the wheel property by using the HTML Element's instance. 

 const carousel = document.querySelector('smart-carousel');
 carousel.wheel = false;

Get the wheel property. 

 const carousel = document.querySelector('smart-carousel');
 let wheel = carousel.wheel;

Events

changeCustomEvent

Triggered when the active ( in view ) slide is changed.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onChange

Arguments

evCustomEvent
ev.detailObject
ev.detail.index - The index of the new active slide.
ev.detail.previousIndex - The index of the previous slide that was active.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of change event. 

const carousel = document.querySelector('smart-carousel');
carousel.addEventListener('change', function (event) {
    const detail = event.detail,
        index = detail.index,
        previousIndex = detail.previousIndex;

	// event handling code goes here.
})

changingCustomEvent

Triggered when the process of slide changing starts.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onChanging

Arguments

evCustomEvent
ev.detailObject
ev.detail.index - The index of the new active slide.
ev.detail.previousIndex - The index of the previous slide that was active.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of changing event. 

const carousel = document.querySelector('smart-carousel');
carousel.addEventListener('changing', function (event) {
    const detail = event.detail,
        index = detail.index,
        previousIndex = detail.previousIndex;

	// event handling code goes here.
})

swipeleftCustomEvent

This event is triggered when the user swipes to the left inside the Carousel.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onSwipeleft

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of swipeleft event. 

const carousel = document.querySelector('smart-carousel');
carousel.addEventListener('swipeleft', function (event) {
	// event handling code goes here.
})

swiperightCustomEvent

This event is triggered when the user swipes to the right inside the Carousel.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onSwiperight

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of swiperight event. 

const carousel = document.querySelector('smart-carousel');
carousel.addEventListener('swiperight', function (event) {
	// event handling code goes here.
})

Methods

next(): void

Navigates to the next slide.


Invoke the next method.

const carousel = document.querySelector('smart-carousel');
carousel.next("");

Try a demo showcasing the next method.

pause(): void

Pauses the slide show if slideShow is enabled.


Invoke the pause method.

const carousel = document.querySelector('smart-carousel');
carousel.pause("");

Try a demo showcasing the pause method.

play(): void

Starts the slide show if slideShow is enabled.


Invoke the play method.

const carousel = document.querySelector('smart-carousel');
carousel.play("");

Try a demo showcasing the play method.

prev(): void

Navigates to the previous slide.


Invoke the prev method.

const carousel = document.querySelector('smart-carousel');
carousel.prev("");

Try a demo showcasing the prev method.

slideTo( index: number): void

Navigates to a specific slide with the given index.

Arguments

indexnumber

The index of the target slide.


Invoke the slideTo method.

const carousel = document.querySelector('smart-carousel');
carousel.slideTo("3");

Try a demo showcasing the slideTo method.

CSS Variables

--smart-carousel-default-widthvar()

Default value

"600px"

default width of the element

--smart-carousel-default-heightvar()

Default value

"200px"

default height of the element

--smart-carousel-3d-mode-slide-widthvar()

Default value

"400px"

default width of a slide in 3d mode

--smart-carousel-3d-mode-slide-heightvar()

Default value

"400px"

default height of a slide in 3d mode

--smart-carousel-multiple-mode-slide-widthvar()

Default value

"200px"

default width of a slide in multiple mode