Carousel

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

<template>
  <div>
    <b-carousel
      id="carousel-1"
      v-model="slide"
      :interval="4000"
      controls
      indicators
      background="#ababab"
      img-width="1024"
      img-height="480"
      style="text-shadow: 1px 1px 2px #333;"
      @sliding-start="onSlideStart"
      @sliding-end="onSlideEnd"
    >
      <!-- Text slides with image -->
      <b-carousel-slide
        caption="First slide"
        text="Nulla vitae elit libero, a pharetra augue mollis interdum."
        img-src="https://picsum.photos/1024/480/?image=52"
      ></b-carousel-slide>

      <!-- Slides with custom text -->
      <b-carousel-slide img-src="https://picsum.photos/1024/480/?image=54">
        <h1>Hello world!</h1>
      </b-carousel-slide>

      <!-- Slides with image only -->
      <b-carousel-slide img-src="https://picsum.photos/1024/480/?image=58"></b-carousel-slide>

      <!-- Slides with img slot -->
      <!-- Note the classes .d-block and .img-fluid to prevent browser default image alignment -->
      <b-carousel-slide>
        <template #img>
          <img
            class="d-block img-fluid w-100"
            width="1024"
            height="480"
            src="https://picsum.photos/1024/480/?image=55"
            alt="image slot"
          >
        </template>
      </b-carousel-slide>

      <!-- Slide with blank fluid image to maintain slide aspect ratio -->
      <b-carousel-slide caption="Blank Image" img-blank img-alt="Blank image">
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse eros felis, tincidunt
          a tincidunt eget, convallis vel est. Ut pellentesque ut lacus vel interdum.
        </p>
      </b-carousel-slide>
    </b-carousel>

    <p class="mt-4">
      Slide #: {{ slide }}<br>
      Sliding: {{ sliding }}
    </p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        slide: 0,
        sliding: null
      }
    },
    methods: {
      onSlideStart(slide) {
        this.sliding = true
      },
      onSlideEnd(slide) {
        this.sliding = false
      }
    }
  }
</script>

<!-- b-carousel.vue -->

Please be aware that nested carousels are not supported.

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 <b-carousel-slide>, you can set the image width and height via the img-width and img-height props on <b-carousel> 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, <b-carousel-slide> uses the <b-img> component to render the images. The img-* props map to the corresponding props available to <b-img>.

Interval

Carousel defaults to an interval of 5000ms (5 seconds). You can change the interval between slides by setting the interval prop to the desired number of milliseconds. The smallest supported sliding interval is 1000ms (1 second).

In browsers where the Page Visibility API is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.). Sliding will resume when the browser tab is active.

Pausing the carousel

To pause the carousel from auto sliding, set the interval prop to 0. To restart a paused carousel, set the interval back to the desired number of ms.

When the carousel is paused, the user can still switch slides via the controls (if enabled) or touch swipe (on touch enabled devices, if not disabled).

When the users mouse hovers the carousel it will automatically pause, and will automatically restart when the mouse leaves the carousel. To disable this feature, set the no-hover-pause prop on <b-carousel>.

Controls and indicators

Set the prop controls to enable the previous and next control buttons.

Set the prop indicators to show the slide indicator buttons.

Both indicators and controls can be set at the same time or independently.

Carousel slide content

b-carousel-slide provides several props and slots for placing content in the slide.

Props

caption Text to use as the main title on the slide (placed inside the inner element which has the class carousel-caption)
text Textual placed under the title (placed inside the inner element which has the class carousel-caption)
img-src URL of image to be placed into the background of the slide
caption-html Alternate prop to the caption prop, which supports HTML strings
html Alternate prop to the text prop, which supports HTML strings

Warning: Be cautious of using the caption-html and html props to display user supplied content, as it may make your application vulnerable to XSS attacks, if you do not first sanitize the user supplied string.

Named slots

default content that will be placed inside of the inner element which has the class carousel-caption. Appears after any content from the caption and text props.
img content to place into the background of the slide. Despite the slot's name, you can place almost any content in this slot in lieu of using the default slot or caption and text props.

Carousel animation

Carousel, by default, uses a sliding animation. You can change the slide animation to a cross-fade animation, or disable animation completely.

Crossfade animation

Set the <b-carousel> fade prop to true to animate slides with a fade transition instead of the default slide animation.

<div>
  <b-carousel
    id="carousel-fade"
    style="text-shadow: 0px 0px 2px #000"
    fade
    indicators
    img-width="1024"
    img-height="480"
  >
    <b-carousel-slide
      caption="First slide"
      img-src="https://picsum.photos/1024/480/?image=10"
    ></b-carousel-slide>
    <b-carousel-slide
      caption="Second Slide"
      img-src="https://picsum.photos/1024/480/?image=12"
    ></b-carousel-slide>
    <b-carousel-slide
      caption="Third Slide"
      img-src="https://picsum.photos/1024/480/?image=22"
    ></b-carousel-slide>
  </b-carousel>
</div>

<!-- b-carousel-fade.vue -->

Disable animation

Set the <b-carousel> no-animation prop to true to disable slide animation.

<div>
  <b-carousel
    id="carousel-no-animation"
    style="text-shadow: 0px 0px 2px #000"
    no-animation
    indicators
    img-width="1024"
    img-height="480"
  >
    <b-carousel-slide
      caption="First slide"
      img-src="https://picsum.photos/1024/480/?image=10"
    ></b-carousel-slide>
    <b-carousel-slide
      caption="Second Slide"
      img-src="https://picsum.photos/1024/480/?image=12"
    ></b-carousel-slide>
    <b-carousel-slide
      caption="Third Slide"
      img-src="https://picsum.photos/1024/480/?image=22"
    ></b-carousel-slide>
    <b-carousel-slide
      caption="Fourth Slide"
      img-src="https://picsum.photos/1024/480/?image=23"
    ></b-carousel-slide>
  </b-carousel>
</div>

<!-- b-carousel-no-animation.vue -->

Slide wrapping

Normally when the carousel reaches one end or the other in the list of slides, it will wrap to the opposite end of the list of slides and continue cycling.

To disable carousel slide wrapping, set the no-wrap prop to true.

Hide slide text content on small screens

On smaller screens you may want to hide the captions and headings. You can do so via the content-visible-up prop of <b-carousel-slide>. The prop accepts a breakpoint name (i.e. sm, md, lg, xl, or custom breakpoint names if you have defined them), and will hide the headings and captions on screens smaller than the breakpoint.

Touch swipe support

On touch enabled devices, users can switch slides by swiping left or right on the carousel. To disable touch control, set the no-touch prop to true.

`v-model` support

Programmatically control which slide is showing via v-model (which binds to the value prop). Note, that slides are indexed starting at 0.

Programmatic slide control

The <b-carousel> instance provides several public methods for controlling sliding:

Method	Description
`setSlide(index)`	Go to slide specified by `index`
`next()`	Go to next slide
`prev()`	Go to previous slide
`pause()`	Pause the slide cycling
`start()`	Start slide cycling (prop `interval` must have a value)

You will need a reference (via this.$refs) to the carousel instance in order to call these methods:

<template>
  <b-carousel ref="myCarousel" .... >
    <!-- slides go here -->
  </b-carousel>
</template>

<script>
  export default {
    // ...
    methods: {
      prev() {
        this.$refs.myCarousel.prev()
      },
      next() {
        this.$refs.myCarousel.next()
      }
    }
  }
</script>

Accessibility

Carousels are generally not fully compliant with accessibility standards, although we try to make them as accessible as possible.

By providing a document unique value via the id prop, <b-carousel> will enable accessibility features. It is highly recommended to always add an ID to all components.

All carousel controls and indicators have aria labels. These can be customized by setting the various label-* props.

Note: The animation effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation for additional details.

Component reference

`<b-carousel>`

View source

<b-carousel> Properties
<b-carousel> v-model
<b-carousel> Slots
<b-carousel> Events

Properties

All property default values are globally configurable.

Property (Click to sort Ascending)	Type (Click to sort Ascending)	Default	Description
`background`	`String`		Set the CSS color of the carousel's background
`controls`	`Boolean`	`false`	Enable the previous and next controls
`fade`	`Boolean`	`false`	When set, changes the slide animation to a crossfade instead of a sliding effect
`id`	`String`		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`	`Number` or `String`		Set the default image 'height' attribute for all b-tab children
`img-width`	`Number` or `String`		Set the default image 'width' attribute for all b-tab children
`indicators`	`Boolean`	`false`	Enable the indicator buttons for jumping to specific slides
`interval`	`Number`	`5000`	Set the delay time (in milliseconds) between slides
`label-goto-slide`	`String`	`'Goto slide'`	Sets the prefix for the 'aria-label' on the slide indicator controls. Will be suffixed with the slide number (1 indexed)
`label-indicators`	`String`	`'Select a slide to display'`	Sets the 'aria-label' on the indicator controls wrapper
`label-next`	`String`	`'Next slide'`	Sets the 'aria-label' value for the next slide control
`label-prev`	`String`	`'Previous slide'`	Sets the 'aria-label' value for the previous slide control
`no-animation`	`Boolean`	`false`	When set, disables animation when transitioning between slides
`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` v2.0.0+	`Boolean`	`false`	Do not restart the slide show when then end is reached
`value` v-model	`Number`	`0`	The currently active slide (zero-indexed)

`v-model`

Property	Event
`value`	`input`

Slots

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

Events

Event	Arguments	Description
`sliding-end`	`slide` - Slide number that was slid to	Emitted when transitioning to a new slide has ended
`sliding-start`	`slide` - Slide number that is being slid to	Emitted when transitioning to a new slide has started

`<b-carousel-slide>`

View source

<b-carousel-slide> Properties
<b-carousel-slide> Slots

Properties

All property default values are globally configurable.

Property (Click to sort Ascending)	Type (Click to sort Ascending)	Default	Description
`background`	`String`		CSS color to use as the slide's background color
`caption`	`String`		Text content to place in the caption
`caption-html` Use with caution	`String`		HTML string 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`		Specify the breakpoint that the textual content will start to be shown. Leave at default to always show the textual content
`id`	`String`		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`		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`	`Number` or `String`		Set the default image 'height' attribute for all b-tab children
`img-src`	`String`		Sets the URL of the image
`img-width`	`Number` or `String`		Set the default image 'width' attribute for all b-tab children
`text`	`String`		Text content to place in the text of the slide
`text-html` Use with caution	`String`		HTML string 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 content

Caution: Props that support HTML strings (*-html) can be vulnerable to Cross Site Scripting (XSS) attacks when passed raw user supplied values. You must properly sanitize the user input first!

Slots

Name	Description
`default`	Content to place in the carousel slide
`img`	Slot for img element or image component

Importing individual components

You can import individual components into your project via the following named exports:

Component	Named Export	Import Path
`<b-carousel>`	`BCarousel`	`bootstrap-vue`
`<b-carousel-slide>`	`BCarouselSlide`	`bootstrap-vue`

Example:

import { BCarousel } from 'bootstrap-vue'
Vue.component('b-carousel', BCarousel)

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export	Import Path
`CarouselPlugin`	`bootstrap-vue`

Example:

import { CarouselPlugin } from 'bootstrap-vue'
Vue.use(CarouselPlugin)

Sizing

Interval

Pausing the carousel

Controls and indicators

Carousel slide content

Props

Named slots

Carousel animation

Crossfade animation

Disable animation

Slide wrapping

Hide slide text content on small screens

Touch swipe support

v-model support

Programmatic slide control

Accessibility

Component reference

Properties

v-model

Slots

Events

Properties

Slots

Importing individual components

Importing as a Vue.js plugin

`v-model` support

`v-model`