# Carousel

Kickstand UI's carousel component is designed to provide users with a way to cycle through content such as images, text, and links.

Stapler in Jello

Identity Theft

Protect Yourself

Asian Jim

(Not really Jim)

Dwight VS Dwight

<ks-carousel>
    <ks-carousel-slide
        alt="Jim Pranks Dwight"
        src="/images/demo/stapler_in_jello.jpg"
        >
        <h2>Stapler in Jello</h2>
    </ks-carousel-slide>
    <ks-carousel-slide
        alt="Jim Pranks Dwight"
        src="/images/demo/jim_as_dwight.jpeg"
        >
        <h2>Identity Theft</h2>
        <ks-button>Protect Yourself</ks-button>
    </ks-carousel-slide>
    <ks-carousel-slide
        alt="Jim Pranks Dwight"
        src="/images/demo/asian_jim.png"
        >
        <h2>Asian Jim</h2>
        <p>(Not really Jim)</p>
    </ks-carousel-slide>
    <ks-carousel-slide
        alt="Jim Pranks Dwight"
        src="/images/demo/dwight_fights_himself.png"
        >
        <h2>Dwight VS Dwight</h2>
    </ks-carousel-slide>
</ks-carousel>

Note

Before using a carousel, please consider an alternate way of displaying content to your users. Carousel engagement is incredibly low, accessibility is difficult to get right, and can be distracting from your message. For more information, check out shouldiuseacarousel.com (opens new window).

# Hide Indicators

Stapler in Jello

Identity Theft

Protect Yourself

Asian Jim

(Not really Jim)

Dwight VS Dwight

<ks-carousel hide-indicators>
    ...
</ks-carousel>

# Hide Controls

Stapler in Jello

Identity Theft

Protect Yourself

Asian Jim

(Not really Jim)

Dwight VS Dwight

<ks-carousel hide-controls>
    ...
</ks-carousel>

# Thumbnails

Stapler in Jello

Identity Theft

Protect Yourself

Asian Jim

(Not really Jim)

Dwight VS Dwight

<ks-carousel thumbnails>
    ...
</ks-carousel>

# Autoplay

Stapler in Jello

Identity Theft

Protect Yourself

Asian Jim

(Not really Jim)

Dwight VS Dwight

<ks-carousel autoplay>
    ...
</ks-carousel>

# Timer

If autoplay is true, you can adjust the time interval between each slide using the timer property (value is in milliseconds).

<ks-carousel autoplay timer="10000">
    ...
</ks-carousel>

# Play/Pause

In order to provide better usability, a play and pause button will be added to the carousel in case content moves too quickly or if it is too distracting.

# Slide Content

There are a number of great properties available for <ks-carousel-slide>, but one of the nicest features is the ability to place content wherever you want on the slide using the align and position properties. the table below represents a slide and the available positions for slide content and the property values that will make it happen.

align="left"
position="top"
align="center"
position="top"
align="right"
position="top"
align="left"
position="center"
align="center"
position="center"
align="right"
position="center"
align="left"
position="bottom"
align="center"
position="bottom"
align="right"
position="bottom"

Top / Left

Default

Bottom / Right

# Accessibility

WARNING

Carousels, in general, are not very accessible and are not actually very effective ways of displaying content. If possible, static content with relevant images is recommended.

In order to make the carousel more accessible, it is treated like a tab component and the following roles and states have been implemented:

  • The slides are assigned role="tabpanel" and the indicators are assigned role="tablist" and role="tab" respectively.
  • The slides are hidden by default (aria-hidden="true") and are set to false when they are selected
  • Indicators are not selected by default (aria-selected="false") and are set to true when the related slide has been selected

# Properties

Property Attribute Type Default Description
hideIndicators hide-indicators boolean false hide indicators displaying current and number of slides
hideControls hide-controls boolean false hide controls for moving between slides
thumbnails thumbnails boolean false replaces indicators with image thumbnails
autoplay autoplay boolean false automatically rotate through slides
timer timer number 6000 time interval between each slide (in milliseconds)
Property Attribute Type Default Description
align align "start", "center", or "end" 'center' horizontal alignment of slide content
position position "start", "center", or "end" vertical alignment of slide content
alt alt string undefined alt text for slide image
lazy lazy boolean false lazy-load slide image
src src string undefined image source
threshold threshold number 300 how soon the lazy-loaded image should load before the component enters the viewport (in pixels)
clickable clickable boolean false makes entire slide clickable
href href string undefined where to link the slide to
height height number undefined sets the height attribute on the img element
width width number undefined sets the width attribute on the img element
aspectRatio aspect-ratio string undefined sets the width and height attribute on the img element based on