Carousel

The Carousel component is a slideshow for cycling through a set of elements — images or text 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.

Show code

HTML

<section>
    <o-carousel indicator-inside>
        <o-carousel-item v-for="(carousel, i) in carousels" :key="i">
            <article
                class="example-slide"
                :style="{ 'background-color': carousel.color }">
                <h1>{{ carousel.text }}</h1>
            </article>
        </o-carousel-item>
    </o-carousel>
</section>

JS

const carousels = [
    { 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" },
];

SCSS

.example-slide {
    padding: 9rem 4.5rem;
    color: #ffffff;
    text-align: center;
}

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="carousel"
        :indicators="indicators"
        :indicator-inside="indicatorInside"
        :indicator-position="indicatorPosition"
        :indicator-style="indicatorStyle">
        <o-carousel-item v-for="(item, i) in items" :key="i">
            <img :src="item.image" :alt="item.title" />
        </o-carousel-item>
    </o-carousel>

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

JS

import { ref } from "vue";

const carousel = ref(1);

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

const items = [
    {
        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="items.length" />
        </o-field>
        <o-field label="Items to List">
            <o-input
                v-model="itemsToList"
                type="number"
                number
                min="1"
                :max="items.length - 1" />
        </o-field>
    </o-field>

    <o-carousel
        :key="itemsToList + itemsToShow"
        v-model="carousel"
        :arrows="arrows"
        :arrows-hover="arrowsHover"
        :dragable="dragable"
        :items-to-show="itemsToShow"
        :items-to-list="itemsToList"
        :repeat="repeat">
        <o-carousel-item v-for="(item, i) in items" :key="i">
            <img :src="item.image" :alt="item.title" />
        </o-carousel-item>
    </o-carousel>

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

JS

import { ref } from "vue";

const carousel = 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 items = [
    {
        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)">
        <o-carousel-item v-for="(item, i) in items" :key="i" clickable>
            <div class="image">
                <img :src="item.image" :alt="item.title" />
            </div>
        </o-carousel-item>

        <template #indicators="{ active, switchTo }">
            <o-carousel
                :model-value="active"
                :indicators="indicators"
                :items-to-show="itemsToShow"
                :breakpoints="breakpoints"
                @update:model-value="switchTo($event)">
                <o-carousel-item
                    v-for="(item, i) in items"
                    :key="i"
                    clickable
                    item-class="img-indicator"
                    item-active-class="img-indicator-active">
                    <img :src="item.image" :alt="item.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 indicators = ref(false);
const itemsToShow = ref(2);
const breakpoints = ref({
    768: {
        itemsToShow: 4,
    },
    960: {
        itemsToShow: 6,
    },
});

const items = [
    {
        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): void {
    gallery.value = value;

    if (value) document.documentElement.classList.add("o-clipped");
    else document.documentElement.classList.remove("o-clipped");
}

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="carousel"
                type="number"
                number
                min="0"
                :max="carousels.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="carousel"
        :dragable="dragable"
        :autoplay="autoplay"
        :pause-hover="pauseHover"
        :interval="interval"
        :repeat="repeat"
        :arrows-hover="false">
        <o-carousel-item v-for="(slide, i) in carousels" :key="i">
            <section
                class="example-slide"
                :style="{ 'background-color': slide.color }">
                <h1>{{ slide.text }}</h1>
                <o-input :placeholder="slide.text" />
                <p>A link that <a href="#arrow">goes to arrow</a></p>
            </section>
        </o-carousel-item>
    </o-carousel>
</section>

JS

import { ref } from "vue";

const carousels = [
    { 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" },
];

const carousel = ref(0);

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

SCSS

.example-slide {
    padding: 9rem 4.5rem;
    color: #ffffff;
    text-align: center;
}

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	number	-	0
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 number - active index	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
arrow	Override the arrows	has-prev boolean - has prev arrow button prev (): void - switch to prev item function has-next boolean - has next arrow button next (): void - switch to next item function
default	Display carousel item
indicators	Override the indicators	active number - active index switch-to (idx: number): void - switch to item function
indicator	Override the indicator elements	index index - indicator index
overlay	Overlay element

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
override	Override existing theme classes completely	boolean	-

Slots

Name	Description	Bindings
default	Default content

Class Inspector

Classes applied to the element:

How does the Class props 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 items container element.
itemsDraggingClass	Class of items container element when dragging.	dragable
iconClass	Class of icon button elements.
iconPrevClass	Class of prev icon button element.
iconNextClass	Class of next icon button element.
iconAutoplayClass	Class of autoplay icon button element.
indicatorsClass	Class of indicators tablist element.
indicatorsInsideClass	Class of indicators tablist element when inside.	indicatorInside
indicatorsPositionClass	Class of indicators tablist element with position.	indicatorPosition
indicatorClass	Class of indicator tab element.
indicatorItemClass	Class of indicator item element.
indicatorItemActiveClass	Class of indicator item element when active.
indicatorItemStyleClass	Class of indicator item element to separate different styles.	indicatorStyle
▷ itemClass	Class of item element.
▷ itemActiveClass	Class of item element when active.
▷ itemClickableClass	Class of item element when clickable.	clickable

Sass variables

Current theme ➜ Oruga

SASS Variable	Default
$carousel-arrow-background	var(--#{$prefix}white)
$carousel-arrow-color	var(--#{$prefix}primary)
$carousel-arrow-icon-spaced	1.5rem
$carousel-arrow-top	50%
$carousel-arrow-size	1.5rem
$carousel-arrow-border-radius	var( --#{$prefix}base-border-radius-rounded)
$carousel-arrow-border	1px solid $carousel-arrow-background
$carousel-arrow-transition	var(--#{$prefix}transition-duration) var(--#{$prefix}transition-timing)
$carousel-autoplay-top	1em
$carousel-autoplay-left	$carousel-arrow-icon-spaced
$carousel-autoplay-right	unset
$carousel-autoplay-bottom	unset
$carousel-indicators-background	rgba(var(--#{$prefix}white), 0.5)
$carousel-indicators-padding	0.5rem
$carousel-indicator-margin	0 0.5rem 0 0
$carousel-indicator-color	var(--#{$prefix}primary)
$carousel-indicator-background	var(--#{$prefix}white)
$carousel-indicator-border	1px solid $carousel-indicator-color
$carousel-indicator-active-background	$carousel-indicator-color
$carousel-indicator-active-border	1px solid $carousel-indicator-color
$carousel-indicator-transition	var(--#{$prefix}transition-duration) var(--#{$prefix}transition-timing)
$carousel-indicator-size	10px
$carousel-indicator-dots-border-radius	var( --#{$prefix}base-border-radius)
$carousel-indicator-lines-height	5px
$carousel-indicator-lines-width	25px
$carousel-items-transition	all var(--#{$prefix}transition-duration) var(--#{$prefix}transition-timing) 0s
$carousel-item-border	2px solid transparent
$carousel-overlay-background	hsla(0, 0%, 4%, 0.86)
$carousel-overlay-zindex	40

See ➜ 📄 Full 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 ➜ 📄 Full scss file

Current theme ➜ Bootstrap

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