Carousel

The Carousel component is a slideshow widget for cycling through a set of elements — images or texts — like a carousel, referred to as slides, by sequentially displaying a subset of one or more slides. One slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view.

The component implements the W3C ARIA APG Carousel Pattern.

Examples

Base

Here is a basic example of a carousel with some slides. When no value is set for an item, the index of the slide is used to as v-model value.

Show code

HTML

<section>
    <o-carousel v-model="currentSlide" indicator-inside>
        <o-carousel-item v-for="slide in slides" :key="slide.title">
            <article
                :style="{
                    'background-color': slide.color,
                    padding: '9rem 4.5rem',
                    color: '#ffffff',
                    'text-align': 'center',
                }">
                <h1>{{ slide.title }}</h1>
            </article>
        </o-carousel-item>
    </o-carousel>

    <p><b>Current slide index:</b> {{ currentSlide }}</p>
</section>

JS

import { ref } from "vue";

const currentSlide = ref<number>();

const slides = [
    { title: "Slide 1", color: "#445e00" },
    { title: "Slide 2", color: "#006724" },
    { title: "Slide 3", color: "#b60000" },
    { title: "Slide 4", color: "#f4c300" },
    { title: "Slide 5", color: "#005c98" },
];

Indicators

Alongside the previous/next controls, slide indicators can be activated using the indicators prop. Indicators allow the user to jump directly to a particular slide. The position can be set with the indicatorPosition and indicatorInside props to display the indicators at the top or bottom and inside or outside the slide. If there is more than one style defined for the indicators in a theme, the style can be customised by using the indicatorStyle prop.

Show code

HTML

<section>
    <o-field grouped>
        <o-field>
            <o-switch v-model="indicators" label="Show indicators" />
        </o-field>
        <o-field>
            <o-switch
                v-model="indicatorInside"
                label="Show indicators inside" />
        </o-field>
        <o-field label="Select indicators position">
            <o-select v-model="indicatorPosition">
                <option value="top">Top</option>
                <option value="bottom">bottom</option>
            </o-select>
        </o-field>
        <o-field label="Select indicators style">
            <o-select v-model="indicatorStyle">
                <option value="dots">Dots</option>
                <option value="lines">Lines</option>
            </o-select>
        </o-field>
    </o-field>

    <o-carousel
        v-model="currentSlide"
        :indicators="indicators"
        :indicator-inside="indicatorInside"
        :indicator-position="indicatorPosition"
        :indicator-style="indicatorStyle">
        <o-carousel-item
            v-for="slide in slides"
            :key="slide.title"
            :value="slide.value"
            :image="slide.image"
            :image-alt="slide.title" />
    </o-carousel>

    <p><b>Current slide index:</b> {{ currentSlide }}</p>
</section>

JS

import { ref } from "vue";

const currentSlide = ref(1);

const indicators = ref(true);
const indicatorInside = ref(true);
const indicatorPosition = ref<string>("top");
const indicatorStyle = ref<string>("dots");

const slides = [
    {
        title: "Slide 1",
        value: 1,
        image: "https://picsum.photos/id/1/1230/500",
    },
    {
        title: "Slide 2",
        value: 2,
        image: "https://picsum.photos/id/2/1230/500",
    },
    {
        title: "Slide 3",
        value: 3,
        image: "https://picsum.photos/id/3/1230/500",
    },
    {
        title: "Slide 4",
        value: 4,
        image: "https://picsum.photos/id/4/1230/500",
    },
    {
        title: "Slide 5",
        value: 5,
        image: "https://picsum.photos/id/5/1230/500",
    },
    {
        title: "Slide 6",
        value: 6,
        image: "https://picsum.photos/id/6/1230/500",
    },
    {
        title: "Slide 7",
        value: 7,
        image: "https://picsum.photos/id/7/1230/500",
    },
];

Options

Instead of using the <o-carousel-item> component directly inside the default slot, an options prop can be set, which allows the options to be set programmatically. All <o-carousel-item> component props can be used as attributes of the item object in the options list.

Show code

HTML

<section>
    <o-carousel v-model="currentSlide" :options="slides" />

    <p><b>Current slide index:</b> {{ currentSlide }}</p>
</section>

JS

import { ref } from "vue";

const currentSlide = ref<number>();

const slides = [
    {
        title: "Slide 1",
        image: "https://picsum.photos/id/1/1230/500",
    },
    {
        title: "Slide 2",
        image: "https://picsum.photos/id/2/1230/500",
    },
    {
        title: "Slide 3",
        image: "https://picsum.photos/id/3/1230/500",
    },
    {
        title: "Slide 4",
        image: "https://picsum.photos/id/4/1230/500",
    },
    {
        title: "Slide 5",
        image: "https://picsum.photos/id/5/1230/500",
    },
    {
        title: "Slide 6",
        image: "https://picsum.photos/id/6/1230/500",
    },
    {
        title: "Slide 7",
        image: "https://picsum.photos/id/7/1230/500",
    },
];

Carousel List

The component is capable of displaying and rotating more than one slide at a time. Therefore, the items-to-show and items-to-list props can be used to specify the number of items to be shown and rotated at once.

Show code

HTML

<section>
    <o-field grouped>
        <o-field>
            <o-switch v-model="arrows" label="Arrow" />
        </o-field>
        <o-field>
            <o-switch
                v-model="arrowsHover"
                :disabled="!arrows"
                label="Arrow on hover" />
        </o-field>
        <o-field>
            <o-switch v-model="dragable" label="Drag event" />
        </o-field>
        <o-field>
            <o-switch v-model="repeat" label="Repeat" />
        </o-field>
    </o-field>
    <o-field grouped>
        <o-field label="Items to Show">
            <o-input
                v-model="itemsToShow"
                type="number"
                number
                min="1"
                :max="slides.length" />
        </o-field>
        <o-field label="Items to List">
            <o-input
                v-model="itemsToList"
                type="number"
                number
                min="1"
                :max="slides.length - 1" />
        </o-field>
    </o-field>

    <o-carousel
        :key="itemsToList + itemsToShow"
        v-model="currentSlide"
        :arrows="arrows"
        :arrows-hover="arrowsHover"
        :dragable="dragable"
        :items-to-show="itemsToShow"
        :items-to-list="itemsToList"
        :repeat="repeat">
        <o-carousel-item
            v-for="slide in slides"
            :key="slide.title"
            :image="slide.image"
            :image-alt="slide.title" />
    </o-carousel>

    <p><b>Current slide index:</b> {{ currentSlide }}</p>
</section>

JS

import { ref } from "vue";

const currentSlide = ref(1);

const arrows = ref(true);
const arrowsHover = ref(true);
const dragable = ref(true);
const itemsToShow = ref(4);
const itemsToList = ref(1);
const repeat = ref(false);

const slides = [
    {
        title: "Slide 1",
        image: "https://picsum.photos/id/1/1230/500",
    },
    {
        title: "Slide 2",
        image: "https://picsum.photos/id/2/1230/500",
    },
    {
        title: "Slide 3",
        image: "https://picsum.photos/id/3/1230/500",
    },
    {
        title: "Slide 4",
        image: "https://picsum.photos/id/4/1230/500",
    },
    {
        title: "Slide 5",
        image: "https://picsum.photos/id/5/1230/500",
    },
    {
        title: "Slide 6",
        image: "https://picsum.photos/id/6/1230/500",
    },
    {
        title: "Slide 7",
        image: "https://picsum.photos/id/7/1230/500",
    },
];

Slideshow

Using the indicators slot, the indicators can be further customised to create a custom style like a picture gallery slideshow. Click on the slide to open the gallery mode.

Show code

HTML

<section>
    <o-carousel
        :autoplay="false"
        :overlay="gallery"
        :arrows="false"
        @click="switchGallery(true)"
        @keydown.esc="gallery && switchGallery(false)">
        <o-carousel-item
            v-for="slide in slides"
            :key="slide.title"
            clickable>
            <div class="image">
                <img :src="slide.image" :alt="slide.title" />
            </div>
        </o-carousel-item>

        <template #indicators="{ activeIndex, switchTo }">
            <o-carousel
                :model-value="activeIndex"
                :indicators="false"
                :breakpoints="breakpoints"
                @update:model-value="switchTo($event)"
                @keydown.left.stop
                @keydown.right.stop>
                <o-carousel-item
                    v-for="slide in slides"
                    :key="slide.title"
                    clickable
                    item-class="img-indicator"
                    item-active-class="img-indicator-active">
                    <img :src="slide.image" :alt="slide.title" />
                </o-carousel-item>
            </o-carousel>
        </template>

        <template #overlay>
            <o-icon
                v-if="gallery"
                icon="times"
                root-class="ex-close-icon"
                clickable
                @click="switchGallery(false)" />
            <div style="color: #ffffff; text-align: center">
                Hello, I'm an overlay!
            </div>
        </template>
    </o-carousel>
</section>

JS

import { ref } from "vue";

const gallery = ref(false);

const breakpoints = {
    0: {
        itemsToShow: 2,
    },
    768: {
        itemsToShow: 4,
    },
    960: {
        itemsToShow: 6,
    },
};

const slides = [
    {
        title: "Slide 1",
        image: "https://picsum.photos/id/1/1230/500",
    },
    {
        title: "Slide 2",
        image: "https://picsum.photos/id/2/1230/500",
    },
    {
        title: "Slide 3",
        image: "https://picsum.photos/id/3/1230/500",
    },
    {
        title: "Slide 4",
        image: "https://picsum.photos/id/4/1230/500",
    },
    {
        title: "Slide 5",
        image: "https://picsum.photos/id/5/1230/500",
    },
    {
        title: "Slide 6",
        image: "https://picsum.photos/id/6/1230/500",
    },
    {
        title: "Slide 7",
        image: "https://picsum.photos/id/7/1230/500",
    },
];

function switchGallery(value: boolean): void {
    gallery.value = value;

    // this removes the scrollbar
    if (value) document.documentElement.classList.add("o-clipped");
    else document.documentElement.classList.remove("o-clipped");

    // this adds gallery close event for esc key
    if (value) document.addEventListener("keydown", switchGalleryOff);
    else document.removeEventListener("keydown", switchGalleryOff);
}

function switchGalleryOff(event: KeyboardEvent): void {
    if (event.key === "Escape") switchGallery(false);
}

SCSS

.image img {
    display: block;
    height: auto;
    width: 100%;
}

.img-indicator {
    filter: grayscale(100%);
}

.img-indicator-active {
    filter: grayscale(0%);
}

.ex-close-icon {
    position: absolute;
    top: 10px;
    right: 10px;
    color: #ffffff;
    z-index: 99;
}

Autoplay

Using the autoplay prop, the carousel will run automatically. The interval prop can be used to set the cycle speed. Moving focus to any of the carousel content, including the tab elements, pauses automatic rotation, when the pause-hover prop is set. If operating system preferences have been set for reduced motion or disabling animations, the auto-rotation is initially paused.

Accessibility Note:

When using autoplay, users must be able to stop and start slide rotation, which is an essential aspect of carousel accessibility for a variety of people with disabilities. People with low vision or a cognitive disability that affects visual processing or reading benefit from being able to control slide rotation so that they have enough time to explore slide content.

Show code

HTML

<section>
    <o-field grouped>
        <o-field>
            <o-switch v-model="autoplay" label="Autoplay" />
        </o-field>
        <o-field>
            <o-switch
                v-model="pauseHover"
                :disabled="!autoplay"
                label="Pause on hover" />
        </o-field>
        <o-field>
            <o-switch v-model="dragable" label="Drag event" />
        </o-field>
        <o-field>
            <o-switch
                v-model="repeat"
                :disabled="!autoplay"
                label="Repeat" />
        </o-field>
    </o-field>

    <o-field grouped>
        <o-field label="Value">
            <o-input
                v-model="currentSlide"
                type="number"
                number
                min="0"
                :max="slides.length - 1" />
        </o-field>
        <o-field label="Interval">
            <o-input
                v-model="interval"
                type="number"
                number
                min="0"
                step="1000"
                :disabled="!autoplay" />
        </o-field>
    </o-field>

    <o-carousel
        v-model="currentSlide"
        :dragable="dragable"
        :autoplay="autoplay"
        :pause-hover="pauseHover"
        :interval="interval"
        :repeat="repeat"
        :arrows-hover="false">
        <o-carousel-item v-for="slide in slides" :key="slide.text">
            <article
                :style="{
                    'background-color': slide.color,
                    padding: '9rem 4.5rem',
                    color: '#ffffff',
                    'text-align': 'center',
                }">
                <h1>{{ slide.text }}</h1>
                <o-input :placeholder="slide.text" />
                <p>A link that <a href="#arrow">goes to arrow</a></p>
            </article>
        </o-carousel-item>
    </o-carousel>
</section>

JS

import { ref } from "vue";

const currentSlide = ref(0);

const dragable = ref(false);
const autoplay = ref(false);
const pauseHover = ref(false);
const interval = ref(3000);
const repeat = ref(false);

const slides = [
    { text: "Slide 1", color: "#445e00" },
    { text: "Slide 2", color: "#006724" },
    { text: "Slide 3", color: "#b60000" },
    { text: "Slide 4", color: "#f4c300" },
    { text: "Slide 5", color: "#005c98" },
];

Carousel Component

A Slideshow for cycling images in confined spaces.

<o-carousel></o-carousel>

Props

Prop name	Description	Type	Values	Default
ariaAutoplayPauseLabel	Accessibility autoplay pause button aria label	string	-	From config: carousel: {   ariaAutoplayPauseLabel: "Stop Automatic Slide Show" }
ariaAutoplayResumeLabel	Accessibility autoplay resume button aria label	string	-	From config: carousel: {   ariaAutoplayResumeLabel: "Start Automatic Slide Show" }
ariaNextLabel	Accessibility next button aria label	string	-	From config: carousel: {   ariaNextLabel: "Next Slide" }
ariaPreviousLabel	Accessibility previous button aria label	string	-	From config: carousel: {   ariaPreviousLabel: "Previous Slide" }
arrows	Show next / prev arrows	boolean	-	From config: carousel: {   arrows: true }
arrowsHover	Show next / prev arrows only on hover	boolean	-	From config: carousel: {   arrowsHover: true }
autoplay	Move item automaticalls after interval	boolean	-	false
breakpoints	Define these props for different screen sizes	Record<number, any>	-
dragable	Enable drag mode	boolean	-	true
iconAutoplayPause	Icon name for autoplay pause button	string	-	From config: carousel: {   iconAutoplayPause: "pause" }
iconAutoplayResume	Icon name for autoplay resume button	string	-	From config: carousel: {   iconAutoplayResume: "play" }
iconNext	Icon name for next button	string	-	From config: carousel: {   iconNext: "chevron-right" }
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: carousel: {   iconPack: undefined }
iconPrev	Icon name for previous button	string	-	From config: carousel: {   iconPrev: "chevron-left" }
iconSize	Icon size	string	small, medium, large	From config: carousel: {   iconSize: undefined }
indicatorInside	Place indicators inside the carousel	boolean	-	false
indicatorPosition	Position of the indicator - depends on used theme	string	-	From config: carousel: {   indicatorPosition: "bottom" }
indicatorStyle	Style of the indicator - depends on used theme	string	-	From config: carousel: {   indicatorStyle: "dots" }
indicators	Enable indicators	boolean	-	true
interval	Timer interval for autoplay	number	-	From config: carousel: {   interval: 3500 }
itemsToList	Number of items to switch at once	number	-	From config: carousel: {   itemsToList: 1 }
itemsToShow	Number of items to show at once	number	-	From config: carousel: {   itemsToShow: 1 }
v-model	The index of the current active element, use v-model to make it two-way binding The selected item value or index, use v-model to make it two-way binding	unknown	-
options	Menu items, unnecessary when default slot is used	CarouselOptions<unknown>	-
overlay	Show an overlay	boolean	-	false
override	Override existing theme classes completely	boolean	-
pauseHover	Pause autoplay on hover	boolean	-	false
repeat	Repeat from the beginning after reaching the end	boolean	-	false

Events

Event name	Properties	Description
update:model-value	value number - updated modelValue prop	modelValue prop two-way binding
change	value unknown - new tab value value unknown - old tab value	on carousel slide change event
click	event event - native event	on item click event

Slots

Name	Description	Bindings
pause	Override the pause/resume button	autoplay boolean - if autoplay is active toggle (): void - toggle autoplay
arrows	Override the arrows	hasPrev boolean - has prev arrow button hasNext boolean - has next arrow button prev (): void - switch to prev item function next (): void - switch to next item function
default	Define the carousel items here
indicators	Override the indicators	activeIndex number - active item index switchTo (idx?: number): void - switch to item function
indicator	Override the indicator elements	index number - indicator index
overlay	Define element to show when overlay is active

CarouselItem Component

A Slideshow item used by the carousel.

<o-carousel-item></o-carousel-item>

Props

Prop name	Description	Type	Values	Default
clickable	Make item clickable	boolean	-	false
image	Background image of the item	string	-
imageAlt	Image alt tag of the background image	string	-
override	Override existing theme classes completely	boolean	-
subtitle	Subtitle of the slide, unnecessary when default slot is used	string	-
title	Title of the slide, unnecessary when default slot is used	string	-
value	Item value (it will be used as the v-model of the wrapper component) - default is the item index	unknown	-

Events

Event name	Properties	Description
click	value unknown - value prop data event event - native event	onclick event
activate		on tab item activate event
deactivate		on tab item deactivate event

Slots

Name	Description	Bindings
default	Override the item content

Class Inspector

Classes applied to the element:

➜ Want to know how does the Class Inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
overlayClass	Class of the root element when overlay.	overlay
wrapperClass	Class of the inner wrapper element.
itemsClass	Class of the items container element.
itemsDraggingClass	Class of the items container element when dragging.	dragable
iconClass	Class of the icon button elements.
iconPrevClass	Class of the prev icon button element.
iconNextClass	Class of the next icon button element.
iconAutoplayClass	Class of the autoplay icon button element.
indicatorsClass	Class of the indicators tablist element.
indicatorsInsideClass	Class of the indicators tablist element when inside.	indicatorInside
indicatorsPositionClass	Class of the indicators tablist element with position.	indicatorPosition
indicatorClass	Class of the indicator tab element.
indicatorItemClass	Class of the indicator item element.
indicatorItemActiveClass	Class of the indicator item element when active.
indicatorItemStyleClass	Class of indicator the item element to separate different styles.	indicatorStyle
▷ itemClass	Class of the item element.
▷ itemActiveClass	Class of the item element when active.
▷ itemClickableClass	Class of the item element when clickable.	clickable
▷ itemTitleClass	Class of the item title element.	title
▷ itemSubtitleClass	Class of the item subtitle element.	subtitle
▷ itemImageClass	Class of the item image wrapper element.	image

Sass Variables

Current theme ➜ Oruga

SASS Variable	Default
$carousel-arrow-icon-spacer	1.5rem
$carousel-arrow-top	50%
$carousel-arrow-size	1.5rem
$carousel-arrow-color	h.useVar("primary")
$carousel-arrow-border-width	1px
$carousel-arrow-border-style	solid
$carousel-arrow-border-color	h.useVar("white")
$carousel-arrow-border-radius	h.useVar("border-radius-rounded")
$carousel-arrow-background-color	$carousel-arrow-border-color
$carousel-arrow-transition	h.useVar("transition-duration") h.useVar("transition-timing")
$carousel-autoplay-top	1em
$carousel-autoplay-left	$carousel-arrow-icon-spacer
$carousel-autoplay-right	unset
$carousel-autoplay-bottom	unset
$carousel-indicators-background	rgba(h.useVar("white"), 0.5)
$carousel-indicators-padding	0.5rem
$carousel-indicator-spacer	0.5rem
$carousel-indicator-size	0.75em
$carousel-indicator-lines-height	5px
$carousel-indicator-lines-width	25px
$carousel-indicator-color	h.useVar("primary")
$carousel-indicator-border	1px solid $carousel-indicator-color
$carousel-indicator-background	h.useVar("white")
$carousel-indicator-transition	h.useVar("transition-duration") h.useVar("transition-timing")
$carousel-indicator-dots-radius	h.useVar("border-radius")
$carousel-indicator-active-background	$carousel-indicator-color
$carousel-indicator-active-border	1px solid $carousel-indicator-color
$carousel-items-transition	all h.useVar("transition-duration") h.useVar("transition-timing") 0s
$carousel-item-border	2px solid transparent
$carousel-overlay-background-color	h.useVar( "overlay-background-color")
$carousel-overlay-zindex	map.get(vars.$zindex, "overlay")

See ➜ 📄 SCSS file

Current theme ➜ Bulma

SASS Variable	Default
$carousel-arrow-icon-spaced	1.5rem
$carousel-arrow-top	50%
$carousel-indicator-spaced	0.5rem
$carousel-overlay-z	40
$carousel-arrow-background	css.getVar("scheme-main")
$carousel-arrow-color	css.getVar("primary")
$carousel-indicator-background	rgba(css.getVar("scheme-invert"), 0.5)
$carousel-indicator-border	css.getVar("scheme-main")
$carousel-indicator-color	css.getVar("primary")
$carousel-overlay-background	hsla( css.getVar(scheme-h), css.getVar(scheme-s), css.getVar(scheme-invert-l), 0.86)

See ➜ 📄 SCSS file

Current theme ➜ Bootstrap

The theme does not have any custom variables for this component.

Current theme ➜ Tailwind

The theme does not have any custom variables for this component.