Configuration

Vue 3 Carousel offers a comprehensive set of configuration options to customize its behavior and appearance. This page documents all available props, their types, default values, and usage guidelines.

All Available Props

Prop	Type	Default	Description
adaptiveHeight	boolean	false	Sizes the carousel to the tallest visible slide and animates the height on navigation. Ignored for vertical directions. 0.19.0
autoplay	number	0	Time interval (in milliseconds) between auto-advancing slides. Set to 0 to disable autoplay.
autoScrollOnFocus	boolean	true	When true, focusing a slide or an element inside it by keyboard or programmatically (not by mouse or touch) slides the carousel to that slide. Set to false to keep the carousel in place, for example when slide links open another page. Content inside off-screen slides is kept out of the tab order; with false, focusing it programmatically no longer scrolls it into view. 0.19.0
breakpointMode	'viewport', 'carousel'	'viewport'	Defines whether breakpoints are calculated based on viewport width or carousel container width.
breakpoints	object	null	Responsive breakpoint configurations. Each breakpoint can override any carousel prop.
clamp	boolean	false	If true will clamp itemsToShow to the number of available slides
classPrefix	string	'carousel'	Prefix for every CSS class the carousel renders (carousel, carousel__slide, ...). Change it when the default collides with other CSS or scripts. The bundled stylesheet targets the default prefix; see Class prefix. 0.19.0
dir	'ltr', 'rtl', 'ttb', 'btt'	'ltr'	Carousel sliding direction. Supports horizontal (ltr/rtl) and vertical (ttb/btt) orientations.
disableWhenSlidesFit	boolean	false	When every slide fits in the viewport and wrapAround is off, hides Navigation and Pagination and stops sliding (drag, wheel, keyboard, autoplay, slideTo, modelValue). The carousel stays laid out and measured. 0.19.0
edgeSpacing	number	0	Space (in pixels) before the first slide and after the last one. Ignored when wrapAround is enabled or slideEffect is 'fade'. 0.18.0
enabled	boolean	true	Controls whether the carousel is interactive. When false, all interactions are disabled.
gap	number	0	Space (in pixels) between carousel slides.
height	number | string	'auto'	Sets the carousel track height. Required for vertical orientation.
i18n	object	{ ... }	Internationalization options for accessibility labels and text content. See i18n for configuration details.
ignoreAnimations	boolean | string | array	false	Specifies which CSS animations should be excluded from slide size calculations. 0.10.0
itemsToScroll	number	1	Number of slides to move when navigating. Useful for creating slide groups.
itemsToShow	number | 'auto'	1	Number of slides visible simultaneously. Use 'auto' for variable width slides.
keyboardNavigation	boolean	true	Enables/disables arrow-key navigation while the carousel is focused. 0.19.0
marquee	boolean	false	Scrolls the slides continuously at a constant speed in a seamless loop. Navigation, drag, wheel and autoplay are disabled in this mode. 0.19.0
marqueeSpeed	number	60	Marquee speed in pixels per second. 0.19.0
modelValue	number	0	Controls the active slide index. Can be used with v-model for two-way binding.
mouseDrag	boolean | object	true	Enables/disables mouse drag navigation. See Drag Options for configuration details.
mouseWheel	boolean | object	false	Enables/disables mouse wheel scrolling for carousel navigation. See Wheel Options for configuration details.
nativeCss	boolean	false	Renders a CSS scroll-snap carousel instead of a transformed track; falls back to the JS mode where unsupported or while marquee is on. See Native CSS mode. 0.19.0
pauseAutoplayOnHover	boolean	false	When true, autoplay (and the marquee) pauses while the mouse cursor is over the carousel.
preventExcessiveDragging	boolean	false	Limits dragging behavior at carousel boundaries for better UX. 0.13.0
slideEffect	'slide', 'fade'	'slide'	Determines the transition effect between slides.
snapAlign	'start', 'end', 'center-odd', 'center-even'	'center'	Determines how slides are aligned within the viewport.
touchDrag	boolean | DragConfig	true	Enables/disables touch navigation on touch-enabled devices. See Drag Options for configuration details.
transition	number	300	Duration of the slide transition animation in milliseconds.
transitionEasing	string	'cubic-bezier(0.25, 0.46, 0.45, 0.94)'	CSS easing function for slide transitions. Accepts any valid CSS timing function. 0.17.0
wrapAround	boolean	false	When true, creates an infinite loop effect by connecting the last slide to the first.

Basic Configuration

These props control the fundamental behavior of the carousel:

<template>
  <Carousel :items-to-show="3" :wrap-around="true" :transition="500">
    <Slide v-for="slide in 10" :key="slide">
      Slide {{ slide }}
    </Slide>
  </Carousel>
</template>

Item Display Options

• itemsToShow: Controls the number of visible slides at once. Accepts numeric values (including decimals) or 'auto'.

  • When set to 'auto', slides determine their own width based on content.
  • Example: :items-to-show="2.5" shows 2 full slides and half of the next one.

• itemsToScroll: Number of slides to move when navigating.

  • Set to a value higher than 1 to create slide groups.
  • Example: :items-to-show="3" :items-to-scroll="3" creates page-like navigation.
  • Without wrapAround and with a value above 1, navigation moves the visible slides by this amount, so a first or last page clamped at the edge still advances a full step; the last step lands on the last (or first) slide. When the slide count is not a multiple of itemsToScroll, that final step is shorter, and stepping back retraces from the end rather than from the original pages.

Direction Settings

• dir: Controls sliding direction. Supports both short and verbose formats:

  • Horizontal: 'ltr'/'left-to-right' or 'rtl'/'right-to-left'
  • Vertical: 'ttb'/'top-to-bottom' or 'btt'/'bottom-to-top'

  For vertical orientations, a fixed height setting is required:

  <Carousel dir="ttb" :height="300">
    <!-- Slides -->
  </Carousel>

Navigation & Control

These props control how users can interact with the carousel:

<template>
  <Carousel 
    :autoplay="3000"
    :pause-autoplay-on-hover="true"
    :mouse-drag="true"
    :touch-drag="true"
    :mouse-wheel="{ threshold: 20 }"
  >
    <!-- Slides -->
  </Carousel>
</template>

• autoplay: Automatically advances slides after the specified interval (in milliseconds).

  • Set to 0 to disable autoplay: :autoplay="0"

• pauseAutoplayOnHover: When true, pauses autoplay while mouse is over the carousel.

• marquee: Scrolls the slides continuously, like a ticker, instead of stepping between them.

  • Example: marquee :marquee-speed="80" moves the track 80px per second.
  • The loop is seamless; wrapAround is not needed. snapAlign and edgeSpacing do not apply.
  • Ignored when slideEffect is 'fade'.
  • Navigation, pagination, drag, mouse wheel, keyboard and v-model are inactive while marquee is on.
  • The Navigation and Pagination addons render nothing while marquee is on, so they can stay in the template when marquee is set per breakpoint.
  • All slides count as visible: the --active, --prev and --next slide classes and slot props are off, and the itemXofY announcement is empty.
  • Pair with pauseAutoplayOnHover to pause while the cursor is over the carousel.
  • Pauses while keyboard focus is on or inside the carousel; a mouse click does not pause it. Use pauseAutoplayOnHover for pointer users.

• mouseDrag and touchDrag: Enable/disable drag navigation.

  • Basic usage: :mouse-drag="true" or :touch-drag="false"
  • Advanced usage: :mouse-drag="{ threshold: 0.5 }" (see Drag Options)

• mouseWheel: Enable/disable mouse wheel navigation.

  • Basic usage: :mouse-wheel="true"
  • Advanced usage: :mouse-wheel="{ threshold: 20 }" (see Wheel Options)

• keyboardNavigation: Enable/disable arrow-key navigation while the carousel is focused.

  • Basic usage: :keyboard-navigation="false"
  • Only arrow keys are affected; focusing a slide still brings it into view, and the Navigation buttons still work.

• preventExcessiveDragging: Improves UX by limiting drag behavior at carousel boundaries.

  • Automatically disabled when wrapAround is enabled

• autoScrollOnFocus: When true (default), keyboard or programmatic focus on a slide, or on an element inside it, slides the carousel to that slide. Pointer focus (mouse or touch) never navigates.

  • Set to false when slide content navigates elsewhere on click and the carousel must not move first: :auto-scroll-on-focus="false"
  • Content inside off-screen slides is removed from the tab order either way; with false, focusing it programmatically no longer scrolls it into view.
  • Known limitation: focusable elements inside a shadow root (web components) cannot be reached, so they stay in the tab order while their slide is off screen.

Visual Customization

These props control the appearance of the carousel:

<template>
  <Carousel 
    :adaptive-height="true"
    :gap="20"
    snap-align="start"
    slide-effect="fade"
    :transition="500"
  >
    <!-- Slides -->
  </Carousel>
</template>

• adaptiveHeight: Sizes the carousel to the tallest visible slide instead of the tallest slide overall, and animates the height on navigation with the transition settings.

  • Example: :adaptive-height="true" for images with mixed aspect ratios.
  • The height prop is the fallback until the slides are measured; slides are re-measured when their content resizes (for example when images load).
  • Visible slides are no longer stretched to the same height; with itemsToShow > 1 shorter slides align to the top.
  • Partially visible slides count too: with a fractional itemsToShow or a centred peek layout, a taller neighbour that peeks into the viewport sets the height.
  • Visible slides size to their content, so percentage heights inside a slide (height: 100%) resolve to auto: give the content an intrinsic or explicit height (images keep their aspect ratio).
  • Ignored for vertical directions (ttb/btt), which need a fixed height.

• gap: Space (in pixels) between slides.

  • Example: :gap="20" creates 20px spacing between slides.

• edgeSpacing: Space (in pixels) before the first slide and after the last one.

  • Example: :edge-spacing="16" shifts the track by 16px at the first and last positions; positions in between are unchanged.
  • Slides keep their size, so pair it with a fractional or 'auto' itemsToShow to keep every slide fully visible at the edges.
  • When every slide already fits in the viewport, only the space before the first slide is applied.
  • Ignored when wrapAround is enabled or slideEffect is 'fade'.

• snapAlign: Controls how slides align within the viewport.

  • 'start': Aligns slides to the beginning of the carousel
  • 'center': Centers the current slide (default)
  • 'end': Aligns slides to the end of the carousel
  • 'center-odd'/'center-even': Special center alignments for odd/even number of visible slides

• slideEffect: Controls the transition effect between slides.

  • 'slide': Standard sliding transition (default)
  • 'fade': Fade effect between slides

• transition: Duration of slide transitions in milliseconds.

  • Example: :transition="500" for a half-second transition.

• transitionEasing: CSS timing function that controls the acceleration curve of transitions.

  • Accepts any valid CSS timing function value
  • Default: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)' (ease-out-quad for smooth deceleration)
  • Common presets:
    • 'ease': Slow start, fast middle, slow end
    • 'ease-in': Slow start, fast end
    • 'ease-out': Fast start, slow end
    • 'ease-in-out': Slow start and end
    • 'linear': Constant speed
  • Custom cubic-bezier examples:
    • 'cubic-bezier(0.68, -0.55, 0.265, 1.55)': Elastic effect
    • 'cubic-bezier(0.4, 0, 0.2, 1)': Material Design standard

  Example with custom easing:

  <Carousel
    :transition="600"
    transition-easing="cubic-bezier(0.4, 0, 0.2, 1)"
  >
    <!-- Slides -->
  </Carousel>

Responsive Behavior

These props control how the carousel adapts to different screen sizes:

<template>
  <Carousel 
    :items-to-show="1"
    breakpoint-mode="carousel"
    :breakpoints="{
      700: {
        itemsToShow: 2,
        snapAlign: 'center',
      },
      1000: {
        itemsToShow: 3,
        snapAlign: 'start',
      }
    }"
  >
    <!-- Slides -->
  </Carousel>
</template>

• breakpoints: Responsive settings that override default props at different widths.

  • Keys represent the minimum width in pixels
  • Values are objects containing any carousel props to override

• breakpointMode: Determines how breakpoints are calculated.

  • 'viewport': Based on browser window width (default)
  • 'carousel': Based on carousel container width

Advanced Options

These props provide additional customization for specific use cases:

• clamp: When true, limits itemsToShow to the actual number of available slides.

  • Useful for preventing empty space when there are fewer slides than itemsToShow.

• enabled: When false, disables all carousel interactions.

  • Useful for conditionally disabling the carousel functionality.

• disableWhenSlidesFit: When true, locks the carousel while every slide already fits in the viewport (never with wrapAround).

  • Navigation and Pagination render nothing, and drag, wheel, keyboard, autoplay, slideTo(), and modelValue changes do nothing.
  • Unlike enabled: false, the carousel keeps its layout and measurements, so it locks and unlocks by itself when a breakpoint changes itemsToShow, the container is resized in 'auto' mode, or slides are added or removed.
  • While locked, the track is pinned at the first slide and modelValue is set to 0; a modelValue change made while locked is applied once the carousel unlocks.
  • The root element gets the is-locked class, and the exposed isLocked / allSlidesFit values report the state for custom addons.

• ignoreAnimations: Excludes specified CSS animations from slide size calculations.

  • Useful when animations are causing layout issues.

• modelValue: Controls the active slide index (for use with v-model).

  • Example: v-model="activeSlide" for two-way binding.

• wrapAround: Creates an infinite loop effect by connecting the last slide to the first.

  • Example: :wrap-around="true" allows continuous navigation in either direction.
  • A v-model change takes the shortest path, looping through the clone slides when that is shorter than crossing the track (not with itemsToShow: 'auto').

Native CSS mode

nativeCss turns the viewport into a CSS scroll-snap container: the browser scrolls, snaps and handles touch, wheel and momentum, and no track transform is applied. Navigation, Pagination, v-model, slide classes and the events other than drag, wheel and loop keep working; slideTo, next and prev scroll the viewport, and the current slide follows the scroll position once scrolling settles.

<Carousel :native-css="true" :items-to-show="2.5" :gap="10" snap-align="start">
  <!-- Slides -->
</Carousel>

• Needs scroll-snap-type support. The server renders the native markup and the browser check runs on mount: where scroll snap is unsupported, the carousel then switches to the regular JS mode. The exposed isNative reports the mode in use, and the root element gets the is-native class.
• Works with itemsToShow (number or 'auto'), itemsToScroll, gap, snapAlign (center-odd/center-even snap as center), dir ltr/rtl/ttb, height, breakpoints, autoplay, pauseAutoplayOnHover, clamp, i18n and arrow keys.
• Turned off in this mode: wrapAround, slideEffect: 'fade', edgeSpacing, mouseDrag, touchDrag, mouseWheel and preventExcessiveDragging (the exposed config shows the effective values). Native scrolling replaces touch drag; trackpads and horizontal or shift+wheel scroll the carousel, but a vertical mouse wheel and mouse drag do not, so add Navigation or Pagination for mouse users. With wrapAround off, autoplay stops at the last slide.
• dir: 'btt' and marquee are not supported natively and use the JS mode.
• The scroll duration is the browser's; transition only times isSliding and the slide-end event, and transitionEasing has no effect.
• Scrollbars are hidden; override .carousel.is-native .carousel__viewport { scrollbar-width: auto } to show them.

Option Details

Drag Options

Both mouseDrag and touchDrag properties accept either a boolean value or a DragConfig object with the following properties:

Property	Type	Default	Description
threshold	number	0.08	Controls the drag distance required to trigger a slide transition, as a fraction of slide width. Higher values require more dragging to trigger a slide change.

Example:

<Carousel :mouse-drag="{ threshold: 0.5 }" :touch-drag="false">
  <!-- Slides -->
</Carousel>

Wheel Options

The mouseWheel property accepts either a boolean value or a WheelConfig object with the following properties:

Property	Type	Default	Description
threshold	number	10	Controls the wheel movement threshold required to trigger a slide transition. Higher values require more scrolling to trigger a slide change.
ignoreCrossAxis	boolean	false	When true, the carousel handles a wheel event only when the delta along its own axis (horizontal for a horizontal carousel, vertical for a vertical one) exceeds threshold and is larger than the cross-axis delta; every other wheel event is left to the browser, so vertical trackpad scrolling over a horizontal carousel scrolls the page. Note that a classic mouse wheel reports only vertical movement, so a horizontal carousel with this option is no longer navigable with a plain mouse wheel. 0.18.0

Example:

<Carousel :mouse-wheel="{ threshold: 20, ignoreCrossAxis: true }">
  <!-- Slides -->
</Carousel>

I18n

The i18n prop allows customization of text content for accessibility and internationalization:

<Carousel 
  :i18n="{
    ariaNextSlide: 'Go to next slide',
    ariaPreviousSlide: 'Go to previous slide'
  }"
>
  <!-- Slides -->
</Carousel>

Available keys:

Key	Defaults	Description
ariaGallery	"Gallery {id}"	Carousel aria-label. Prefer a meaningful name; {id} is an instance id.
ariaNavigateToSlide	"Navigate to slide {slideNumber}"	Sets title and aria-label for pagination buttons to select a slide.
ariaNextSlide	"Navigate to next slide"	Sets title and aria-label for the "Next" navigation button.
ariaPreviousSlide	"Navigate to previous slide"	Sets title and aria-label for the "Previous" navigation button.
iconArrowDown	"Arrow pointing downwards"	Sets title and aria-label for the downward-pointing arrow SVG icon.
iconArrowLeft	"Arrow pointing to the left"	Sets title and aria-label for the left-pointing arrow SVG icon.
iconArrowRight	"Arrow pointing to the right"	Sets title and aria-label for the right-pointing arrow SVG icon.
iconArrowUp	"Arrow pointing upwards"	Sets title and aria-label for the upward-pointing arrow SVG icon.
itemXofY	"Item {currentSlide} of {slidesCount}"	Provides screen readers with the current slide's position in the sequence.

If you translate ariaGallery, keep {id} in it, or give each carousel its own label. If a page mounts several Vue apps, also set app.config.idPrefix per app. A meaningful label per carousel is best for screen-reader users.