Carousel

The carousel is a slideshow for cycling through a series of content. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators.

Nested carousels are not supported. You should also be aware that carousels in general can often cause usability and accessibility challenges.

Basic usage

HTML

template

<BCarousel controls>
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=1" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=2" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=3" />
</BCarousel>

Sizing

Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. When using images in each slide, ensure they all have the same dimensions (or aspect ratio).

When using img-src or img-blank on <BCarouselSlide>, you can set the image width and height via the img-width and img-height props on <BCarousel> and have these values automatically applied to each carousel-slide image.

Note that images will still be responsive and automatically grow or shrink to fit within the width of its parent container.

Internally, <BCarouselSlide> uses the <BImg> component to render the images. The img-* props map to the corresponding props available to <BImg>.

Indicators

With the indicators prop, can add indicators to the Carousel, along side the previous/next controls. The indicators let users jump to a particular slide.

HTML

template

<BCarousel indicators>
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=4" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=5" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=6" />
</BCarousel>

Captions

You can add captions to a particular slide using the following methods: using the caption prop, that will render its text, by using captionHtml prop, which will render html, or by using the caption slot.

First Caption

HTML

template

<BCarousel controls indicators>
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=7" caption="First Caption" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=9">
    <template #caption> Second Caption </template>
  </BCarouselSlide>
</BCarousel>

Crossfade

You can use the fade prop to animate slides with a fade transition instead of a slide.

HTML

template

<BCarousel fade controls indicators>
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=10" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=11" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=12" />
</BCarousel>

Autoplaying Carousels

You can make your Carousels autoplay on a page load by setting the ride prop to carousel. Autoplaying Carousels are automatically paused when hovering with a mouse. You can disable pausing during hover by using the noHoverPause prop.

For accessibility reasons, we recommend avoiding the use of autoplaying carousels. If your page does include an autoplaying carousel, we recommend providing an additional button or control to explicitly pause/stop the carousel.

See WCAG 2.1 Success Criterion 2.2.2 Pause, Stop, Hide.,

Related: Autoplay Manipulation,

Ride

HTML

template

<BCarousel controls indicators ride="carousel">
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=13" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=14" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=15" />
</BCarousel>

When the ride prop is set to true, rather than carousel, the Carousel will not automatically start to cycle on page load. Instead, it will only start after the first user interaction.

HTML

template

<BCarousel controls indicators :ride="true">
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=16" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=17" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=18" />
</BCarousel>

Interval

You can adjust the speed at which the Carousel is moving by adjusting the interval in real time. The default is 5000ms. You can also set intervals per slide by setting the interval prop on the slide

Current Interval Speed: 5000 ms

HTML

vue

<template>
  <BCarousel :interval="slideInterval" controls indicators ride="carousel">
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=19" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=20" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=21" />
  </BCarousel>

  <BButtonGroup>
    <BButton variant="danger" @click="slideInterval = slideInterval - 1000"> Minus 1000 </BButton>
    <BButton variant="success" @click="slideInterval = slideInterval + 1000"> Plus 1000 </BButton>
  </BButtonGroup>

  Current Interval Speed: {{ slideInterval }} ms
</template>

<script setup lang="ts">
import {ref} from 'vue'

const slideInterval = ref(5000)
</script>

Autoplay Reverse

You can use the ride-reverse prop to reverse the direction that the Carousel will autoplay.

HTML

template

<BCarousel controls indicators ride="carousel" :ride-reverse="true">
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=22" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=23" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=24" />
</BCarousel>

Autoplay Manipulation

There can come situations where you need to manually pause/resume the state of an autoplay. BCarousel exposes two functions for this: pause(), resume(). These are accessed through the template ref.

HTML

vue

<template>
  <BCarousel ref="myCarousel" :interval="2500" controls indicators ride="carousel">
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=25" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=26" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=27" />
  </BCarousel>

  <BButtonGroup>
    <BButton variant="danger" @click="pause">Pause</BButton>
    <BButton variant="success" @click="resume">Resume</BButton>
  </BButtonGroup>
</template>

<script setup lang="ts">
import type {BCarousel} from 'bootstrap-vue-next'
import {ref} from 'vue'

const myCarousel = ref<null | InstanceType<typeof BCarousel>>(null)
const pause = () => myCarousel.value?.pause()
const resume = () => myCarousel.value?.resume()
</script>

Touch Swiping

BCarousel comes with automatic support for touch swiping devices. You can disable touch swiping by using the no-touch prop.

Due to touch swiping not being available to everyone, such as a user that is using a mouse, you will likely want to include multiple ways to transition the slides. Otherwise, transitioning can be impossible to those users.

HTML

template

<BCarousel no-touch>
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=28" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=29" />
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=30" />
</BCarousel>

Touch Threshold

You can adjust the distance in pixels it takes to cause a transition to occur by using the touch-threshold prop. A higher value will mean the user needs to swipe a longer distance in order to trigger a transition.

Threshold: 50

HTML

vue

<template>
  <BCarousel :touch-threshold="slideThreshold">
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=31" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=32" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=33" />
  </BCarousel>
  <BButtonGroup class="mt-3">
    <BButton variant="danger" @click="slideThreshold = slideThreshold - 10">Decrease</BButton>
    <BButton variant="success" @click="slideThreshold = slideThreshold + 10">Increase</BButton>
  </BButtonGroup>
  Threshold: {{ slideThreshold }}
</template>

<script setup lang="ts">
import {ref} from 'vue'
const slideThreshold = ref(50)
</script>

Usage With v-model

You are not required to, but you can bind the v-model. This allows for finer control and allows for outside manipulation of the slide, beyond the controls exposed through Exposed Methods.

HTML

vue

<template>
  <BCarousel v-model="slide" controls>
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=1" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=2" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=3" />
  </BCarousel>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const slide = ref(0)
</script>

Changing the Starting Slide

You can change the default starting slide by binding the v-model to the index of the slide you want the Carousel to start at.

Starts at the last index (2)

HTML

vue

<template>
  <BCarousel v-model="slide" indicators>
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=34" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=35" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=36" />
  </BCarousel>
</template>

<script setup lang="ts">
import {ref} from 'vue'

const slide = ref(2)
</script>

Exposed Methods

You are also able to use the built in methods for going to the next, or previous slide using the template ref. In total there are four methods exposed, but this section only covers prev() and next(). Pause and Resume are mentioned here.

prev: goes to the previous slide, ie, moving to the left
next: goes to the next slide, ie, moving to the right
pause: pauses the autoplay timer
resume: resumes the autoplay timer

HTML

vue

<template>
  <BCarousel ref="myCarousel">
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=37" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=38" />
    <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=39" />
  </BCarousel>

  <BButtonGroup class="mt-3">
    <BButton variant="danger" @click="prev">Previous Slide</BButton>
    <BButton variant="success" @click="next">Next Slide</BButton>
  </BButtonGroup>
</template>

<script setup lang="ts">
import type {BCarousel} from 'bootstrap-vue-next'
import {ref} from 'vue'

const myCarousel = ref<null | InstanceType<typeof BCarousel>>(null)

const prev = () => myCarousel.value?.prev()
const next = () => myCarousel.value?.next()
</script>

Full Example

First slide

Some more detailed description or whatever content.

HTML

template

<BCarousel controls indicators>
  <BCarouselSlide img-src="https://picsum.photos/1024/480/?image=40">
    <h1>First slide</h1>
    <p>Some more detailed description or whatever content.</p>
  </BCarouselSlide>
  <BCarouselSlide
    caption="Second slide"
    text="Does the same, just a bit differently."
    img-src="https://picsum.photos/1024/480/?image=41"
  />
  <BCarouselSlide>
    <template #img>
      <BImg
        width="1024"
        height="480"
        src="https://picsum.photos/1024/480/?image=42"
        alt="image slot"
      />
    </template>
    <h1>Third slide</h1>
    <p>Constains a customized background image</p>
  </BCarouselSlide>
  <BCarouselSlide
    img-width="1024"
    img-height="480"
    img-blank
    img-blank-color="pink"
    img-alt="Blank image"
  >
    <h1>Fourth slide</h1>
    <p>No background image</p>
  </BCarouselSlide>
</BCarousel>

Component Reference

<BCarousel>

View Source

<BCarousel> Properties
<BCarousel> Events
<BCarousel> Slots

Adding styles: .carousel

Properties

Prop	Type	Default	Description
background	`string`	`undefined`	Set the CSS color of the carousel's background
controls	`boolean`	`false`	Enable the previous and next controls
controls-next-text	`string`	`'Next'`	Set the text for the "Next" control
controls-prev-text	`string`	`'Previous'`	Set the text for the "Previous" control
fade	`boolean`	`false`	When set, changes the slide animation to a crossfade instead of a sliding effect
id	`string`	`undefined`	Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
img-height	`string`	`undefined`	Set the default image 'height' attribute for all b-tab children
img-width	`string`	`undefined`	Set the default image 'width' attribute for all b-tab children
indicators	`boolean`	`false`	Enable the indicator buttons for jumping to specific slides
indicators-button-label	`string`	`'Slide'`	Set the aria-label for the indicator buttons
interval	`number`	`5000`	Set the delay time (in milliseconds) between slides
keyboard	`boolean`	`true`	Enable keyboard navigation with the right and left arrow keys
label-indicators	`string`	`'Select a slide to display'`	Set the aria-label for the indicators
model-value	`number`	`0`	The index of the currently active slide
no-animation	`boolean`	`false`	When set, disables the animation
no-hover-pause	`boolean`	`false`	When set, disables the pausing of the slide show when the current slide is hovered
no-touch	`boolean`	`false`	Disable controlling the slides via touch swipes
no-wrap	`boolean`	`false`	Do not restart the slide show when then end is reached
ride	`boolean \| 'carousel'`	`false`	Set to "carousel" to animate slides automatically, true to animate on first interaction, false to disable animation
ride-reverse	`boolean`	`false`	When set, the carousel will animate in the reverse direction
touch-threshold	`Numberish`	`50`	The minimum distance the touch swipe must move to prevent the slide show from being paused

Events

Event	Args	Description
click:next	`click: MouseEvent` - Native click event
click:prev	`click: MouseEvent` - Native click event
slid	`value: BvCarouselEvent` - Indicates the slide `direction`, `from`, and `to` indices	Fired when the carousel has completed its slide transition.
slide	`value: BvCarouselEvent` - Indicates the slide `direction`, `from`, and `to` indices	Fires immediately when the carousel starts its slide transition.
update:model-value	`update:model-value: number` - modelValue	Standard event to update the v-model

Slots

Name	Scope	Description
default		Content (slides) to place in the carousel

<BCarouselSlide>

View Source

<BCarouselSlide> Properties
<BCarouselSlide> Slots

Adding styles: .carousel‑item

Properties

Prop	Type	Default	Description
background	`string`	`undefined`	CSS color to use as the slide's background color
caption	`string`	`undefined`	Text content to place in the caption
caption-tag	`string`	`'h3'`	Specify the HTML tag to render instead of the default tag for the caption wrapper
content-tag	`string`	`'div'`	Specify the HTML tag to render instead of the default tag for the content wrapper
content-visible-up	`string`	`undefined`	Specify the breakpoint that the textual content will start to be shown. Leave at default to always show the textual content
id	`string`	`undefined`	Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
img-alt	`string`	`undefined`	Sets the value of the 'alt' attribute on the image
img-blank	`boolean`	`false`	If set, will render a blank image instead of the img-src
img-blank-color	`string`	`'transparent'`	Set the CSS color to use as the fill of the blank image
img-height	`Numberish`	`undefined`	Set the default image 'height' attribute for all b-tab children
img-src	`string`	`undefined`	Sets the URL of the image
img-srcset	`string \| string[]`	`undefined`
img-width	`Numberish`	`undefined`	Set the default image 'width' attribute for all b-tab children
interval	`number`	`undefined`	Set the delay time (in milliseconds) before the slide is shown
text	`string`	`undefined`	Text content to place in the text of the slide
text-tag	`string`	`'p'`	Specify the HTML tag to render instead of the default tag for the text wrapper

Slots

Name	Scope	Description
caption		Content to place in caption
default		Content to place in the carousel slide
img		Slot for img element or image component
text		Content to place in text area of the slide

Carousel ​

Basic usage ​

Sizing ​

Indicators ​

Captions ​

First Caption

Second Caption

Crossfade ​

Autoplaying Carousels ​

Ride ​

Interval ​

Autoplay Reverse ​

Autoplay Manipulation ​

Touch Swiping ​

Touch Threshold ​

Usage With v-model ​

Changing the Starting Slide ​

Exposed Methods ​

Full Example ​

First slide

Second slide

Third slide

Fourth slide

Component Reference

Properties

Events

Slots

Properties

Slots

Carousel

Basic usage

Sizing

Indicators

Captions

Crossfade

Autoplaying Carousels

Ride

Interval

Autoplay Reverse

Autoplay Manipulation

Touch Swiping

Touch Threshold

Usage With v-model

Changing the Starting Slide

Exposed Methods

Full Example