ultimate_carousel

pub package CI Live demo License: MIT

Every Flutter carousel transition in one package. 54 transitions and 15 animated page indicators behind a single widget, with no dependencies besides Flutter.

Six carousels showing the cover flow, cube, ring, deck, page turn and liquid transitions

▶ Try every effect in your browser

It started with a survey of 352 carousel, slider, swiper, card stack, page transformer and page indicator packages on pub.dev. Every distinct transition they offer was collected and written again from scratch behind one API:

  • One widget, every look. Go from a plain slide to a cube, cover flow, 3D ring, card deck or liquid reveal by changing one line.
  • Every feature works with every effect: infinite looping, autoplay, vertical and right-to-left layouts, snapping physics, keyboard, mouse wheel, trackpad and screen readers.
  • Animated indicators that follow the carousel: worm, expanding dots, jumping dot, drop, scrolling dots and more.
  • Your own effects in a few lines with CarouselEffect.custom, or from any widgets with CarouselEffect.builder.
  • Pure Flutter: no dependencies; works on Android, iOS, web, Windows, macOS and Linux.

Install

dependencies:
  ultimate_carousel: ^0.2.0

Quick start

import 'package:ultimate_carousel/ultimate_carousel.dart';

final controller = UltimateCarouselController();

Column(
  children: [
    UltimateCarousel(
      controller: controller,
      effect: const CarouselEffect.coverflow(),
      loop: true,
      autoPlay: const CarouselAutoPlay(),
      height: 240,
      children: [
        for (final url in imageUrls) Image.network(url, fit: BoxFit.cover),
      ],
    ),
    const SizedBox(height: 16),
    CarouselIndicator(
      controller: controller,
      effect: const IndicatorEffect.expandingDots(),
    ),
  ],
)

For long lists use UltimateCarousel.builder(itemCount: …, itemBuilder: …): only the items on screen are built.

Transitions

Pass any of these as effect:. Each one has options; the API docs list them.

Slides and fades

slide
CarouselEffect.slide()
fade
CarouselEffect.fade(zoom: 1.15)
enlarge
CarouselEffect.enlarge()
zoom out
CarouselEffect.zoomOut()
depth
CarouselEffect.depth()
parallax
CarouselEffect.parallax()
stack
CarouselEffect.stack()
accordion
CarouselEffect.accordion()
rotate
CarouselEffect.rotate()
foreground to background
CarouselEffect.foregroundToBackground()
background to foreground
CarouselEffect.backgroundToForeground()
focus
CarouselEffect.focus()
overlap
CarouselEffect.overlap()
uncover
CarouselEffect.uncover()
skew
CarouselEffect.skew()
expo
CarouselEffect.expo()

expo(parallax: 0.2) also lets full-bleed photos drift inside the side items.

Also: fade(crossFade: true), enlarge(strategy: CarouselEnlargeStrategy.height) and .zoom, zoomIn(), rotate(fromTop: true) and uncover(parallax: 0), where the next item waits still underneath.

3D

cube
CarouselEffect.cube()
cube inside
CarouselEffect.cube(inside: true)
flip
CarouselEffect.flip()
coverflow
CarouselEffect.coverflow()
tablet
CarouselEffect.tablet()
ring
CarouselEffect.ring(itemsOnRing: 6)
tilted ring
CarouselEffect.ring(faceViewer: true, tilt: 0.45)
wheel
CarouselEffect.wheel()
cylinder
CarouselEffect.cylinder()
helix
CarouselEffect.helix()
page turn
CarouselEffect.pageTurn()
tunnel
CarouselEffect.tunnel()
crate
CarouselEffect.crate()
orbit
CarouselEffect.ring(faceViewer: true, tilt: 0.5, blur: 5, fade: 0.5)

Also: flip(vertical: true) and ring(showBackItems: true). A tilted ring rises above its items, so give it room: the animations above use viewportFraction: 0.42 (0.32 for the orbit), clipBehavior: Clip.none and space above the carousel. blur and fade give the ring a depth of field; the orbit also sets itemsOnRing: 7 and perspective: 0.003. The crate is made for vertical carousels, like the one above.

Material 3

multi-browse
CarouselEffect.material()
centered hero
CarouselEffect.material(weights: [1, 7, 1])

The weights pick the layout, as in Flutter's CarouselView.weighted: [3, 2, 1] multi-browse, [7, 1] hero, [1, 7, 1] centered hero and [1] full screen. Items are masked, not squeezed: their content keeps its size and the rounded mask around it changes. For the uncontained layout, use the plain slide with alignment: CarouselAlignment.start and a viewportFraction below 1.

Cards

deck
CarouselEffect.deck()
tinder
CarouselEffect.tinder()
fan
CarouselEffect.fan()
arc
CarouselEffect.arc()
scatter
CarouselEffect.scatter()
layered
CarouselEffect.layered()
expanding cards
CarouselEffect.expandingCards()
deal
CarouselEffect.deal()
wallet
CarouselEffect.wallet()

Also: arc(upward: false) for a rainbow and arc(tilt: false) to keep the cards upright. Expanding cards show every item at once, so they suit a handful of items; tap a narrow card to open it with animateToTappedItem. layered(fadeColor: …) fades the neighbours towards your background color instead of white. The deal's glint draws every card through a shader mask; deal(gloss: 0) turns it off. wallet(offset: Offset(0, -0.15)) stacks the cards straight up.

Reveals

circular reveal
CarouselEffect.circularReveal()
liquid
CarouselEffect.liquid()
concentric
CarouselEffect.concentric()
wipe
CarouselEffect.wipe()
curtain
CarouselEffect.curtain()
blinds
CarouselEffect.blinds()
clock
CarouselEffect.clock()
blocks
CarouselEffect.blocks()
slicer
CarouselEffect.slicer()
shutters
CarouselEffect.shutters()

circularReveal(followPointer: true) and liquid() follow the finger, and blocks(random: false) sweeps the blocks in diagonally. The slicer's strips can also shrink or turn away (slicer(style: CarouselSliceStyle.turn)). Slicer and shutters draw each item once per strip, which is fine for pictures but not for heavy widgets.

Creative

Say where the previous and next items go and the carousel moves every item between those poses, like the creative effect of the Swiper web slider. These six looks are Swiper's creative demos:

sink back
CreativeCarouselEffect.sinkBack()
drift apart
CreativeCarouselEffect.driftApart()
push
CreativeCarouselEffect.push()
tumble
CreativeCarouselEffect.tumble()
spin
CreativeCarouselEffect.spin()
door
CreativeCarouselEffect.door()

Or make your own:

CarouselEffect.creative(
  previous: CarouselPose(offset: Offset(-0.2, 0), depth: 100, shade: 0.3),
  next: CarouselPose(offset: Offset(1, 0)),
)

A CarouselPose takes an offset (in item sizes), a depth (logical pixels away from the viewer), rotateX, rotateY and rotateZ (radians), scale, opacity, shade and the origin it turns around. To bring over a Swiper setting, translate: ['-20%', 0, -400] becomes offset: Offset(-0.2, 0), depth: 400, and rotate: [0, 100, 0] becomes rotateY: -100 * pi / 180: Swiper turns the other way around the X and Y axes.

Marquee

Cards gliding past like a marquee

CarouselAutoPlay.scroll glides on its own at a steady speed instead of moving item by item, like a logo strip or a news ticker. It stops while a finger or mouse is on it and glides on when they leave.

UltimateCarousel(
  loop: true,
  viewportFraction: 0.3,
  spacing: 12,
  snapping: CarouselSnapping.none,
  autoPlay: const CarouselAutoPlay.scroll(speed: 40), // logical pixels a second
  children: logos,
)

Indicators

The page indicators, animating

CarouselIndicator(
  controller: controller,
  effect: const IndicatorEffect.worm(
    dotColor: Colors.white24,
    activeDotColor: Colors.white,
  ),
)

Effects: worm (styles normal, thin, underground, thinUnderground), expandingDots, jumpingDot, drop, wave, radio, scrollingDots, slide, scale, swap (styles normal, yRotation, zRotation), colorTransition, fill, segments (story bars), line and fraction ("3 / 10").

Tapping a dot moves the carousel; set axis: Axis.vertical for a vertical carousel. To drive an indicator yourself, for example from a PageView, use CarouselIndicator.value(page: …, count: …).

Options

Option Default What it does
effect slide() The transition.
loop false Wrap around from the last item to the first.
autoPlay off CarouselAutoPlay(interval:, animationDuration:, curve:, reverse:, pauseOnHover:, end:) moves item by item; CarouselAutoPlay.scroll(speed:) glides like a marquee.
scrollDirection horizontal Axis.vertical for vertical carousels.
reverse false The next item comes from the other side. Right-to-left text reverses horizontal carousels on its own.
viewportFraction effect's choice How much of the carousel one item takes.
spacing 0 The gap between items.
alignment center Where the current item sits: start, center or end.
height, aspectRatio none, 16:9 The size when the parent does not set one.
initialPage 0 The first item shown.
snapping single page multiPage for long flings, none for free gliding.
dragSpeed 1 How far a drag moves the carousel compared with the finger.
bounce platform Stretch past the ends of a carousel that does not loop.
onPageChanged (index, reason) with user, autoPlay or controller.
onScrolled The position every frame, for custom animations.
onSettled (index) once the carousel comes to rest after a drag, fling, autoplay step or controller move.
onItemTap, animateToTappedItem Tap callbacks; tapping a side item can bring it to the center.
enableDrag, dragDevices on, all Who can drag the carousel, mouse included.
enableKeyboard, focusNode, autofocus on Arrow keys, Page Up/Down, Home and End.
enableMouseWheel on The mouse wheel and trackpad.
animationDuration, animationCurve 450 ms, ease out Moves started by code, keys and taps.
clipBehavior hard edge Clip.none lets 3D effects spill over the edges.
semanticLabel A label for screen readers.

Controller

final controller = UltimateCarouselController();

controller.nextPage();
controller.previousPage();
controller.animateToPage(3); // A looping carousel takes the short way round.
controller.jumpToPage(0);
controller.jumpTo(2.5); // Halfway between items, for scrubbing or syncing.
controller.startAutoPlay();
controller.stopAutoPlay();

controller.currentIndex; // The item in the center.
controller.realPage; // The position between 0 and itemCount, every frame.

The controller is a ChangeNotifier, so you can listen to it or rebuild with ListenableBuilder.

Animate item content

Every item can read its position with CarouselItemScope.of(context), for example to fade a caption as its slide leaves:

Builder(
  builder: (context) {
    final info = CarouselItemScope.of(context);
    return Opacity(
      opacity: 1 - info.distance.clamp(0.0, 1.0),
      child: const Text('Caption'),
    );
  },
)

CarouselParallax moves its child more slowly than the item around it, which looks great on background images:

CarouselParallax(child: Image.network(url, fit: BoxFit.cover))

Make your own effect

An effect says how to draw an item for its distance from the current page, info.delta (0 is the current item, -1 the previous one, 1 the next one). Write it for a horizontal, left-to-right carousel; the carousel turns and mirrors it for vertical and right-to-left layouts.

final swing = CarouselEffect.custom(
  transform: (info) {
    final matrix = ItemMatrix()
      ..rotateZ(info.delta * 0.3, pivot: const Offset(0, 400))
      ..translate(info.delta * info.layout.slotExtent * 0.8);
    return CarouselItemTransform(
      matrix: matrix.value,
      opacity: 1 - info.distance.clamp(0.0, 1.0) * 0.4,
    );
  },
);

CarouselItemTransform can also clip, shade, blur and move the content inside an item; override shadeColor to shade towards a color other than black. For full control, subclass CarouselEffect and override paintOrder, itemsPerSide or decorate. To make a new reveal, subclass RevealCarouselEffect and return the visible shape from revealPath.

Build a look from widgets

Items spreading out to the sides, made with the builder effect

CarouselEffect.builder hands every item on show to a function that wraps it in any widgets you like. The function gets the item's index, its ratio and the item. The ratio is 0 for the current item, -1 for the furthest item shown before it and 1 for the furthest item shown after it, and it changes smoothly as the carousel moves. Every item starts at the current item's place:

UltimateCarousel(
  effect: CarouselEffect.builder(
    itemsBefore: 2,
    itemsAfter: 2,
    viewportFraction: 0.45,
    builder: (index, ratio, child) => FractionalTranslation(
      translation: Offset(ratio * 1.6, ratio.abs() * 0.15),
      child: Transform.scale(
        scale: 1 - ratio.abs() * 0.4,
        child: Opacity(opacity: 1 - ratio.abs() * 0.6, child: child),
      ),
    ),
  ),
  children: slides,
)

depthOrder picks the items drawn on top: selectedInFront (the default), forward or reverse. The builder works in screen space, so it decides where items go; scrollDirection, reverse and right-to-left text only change which way the user swipes.

This is the API of flutter_custom_carousel, so its effects builders work here unchanged. Its itemCountBefore and itemCountAfter are itemsBefore and itemsAfter, scrollSpeed is dragSpeed, onSettledItemChanged is onSettled and tapToSelect is animateToTappedItem; its default depth order is forward. To use flutter_animate effects, map the ratio onto the animation:

final List<Effect> effects = EffectList().moveY(begin: -250, end: 250);

CarouselEffect.builder(
  builder: (index, ratio, child) => Animate(
    effects: effects,
    value: (ratio + 1) / 2,
    autoPlay: false,
    child: child,
  ),
)

Accessibility

  • Screen readers hear "3 / 10" and can swipe through items; only the current item is read out.
  • The arrow keys and Page Up/Down work while the carousel has focus, and so do Home and End when it does not loop.
  • Autoplay pauses while a pointer is down or hovering, while the app is in the background, and while the system asks apps to reduce motion.

Credits

The transitions were collected from the packages below and written again from scratch here, without copying their code. Thanks to their authors for the ideas.

Package Ideas License
carousel_slider enlarge strategies, autoplay, looping MIT
flutter_carousel_slider cube, accordion, depth, stack, tablet, rotate, zoom, flip, parallax, foreground and background transforms BSD-3-Clause, now MIT
flutter_carousel_widget composable effects, wave and fill indicators, autoplay pausing MIT
card_swiper, flutter_swiper stack and tinder layouts, drop indicator MIT
transformer_page_view page transformers none stated (ideas only)
smooth_page_indicator worm, expanding, jumping, scrolling, slide, scale, swap and color indicators MIT
dots_indicator, page_view_indicators dot sizing, radio rings MIT, BSD-2-Clause
liquid_swipe liquid reveal Apache-2.0
concentric_transition concentric reveal MIT
cube_transition shaded cube Apache-2.0
flutter_3d_carousel, flutter_gallery_3d 3D ring MIT
coverflow_carousel, overlapped_carousel cover flow, overlap BSD-3-Clause, MIT
stacked_card_carousel, flutter_card_swiper, appinio_swiper card decks BSD-3-Clause, MIT
carousel_page_view layered stack BSD-3-Clause
fan_carousel_image_slider, curved_carousel, flywheel_carousel fan and arc MIT, BSD-3-Clause
turn_page_transition, page_turn page turn BSD-3-Clause, MIT
shader_transitions, intro_views_flutter clock, blocks and circle reveals MIT
Swiper creative effect and its demo looks; slicer, shutters and expo sliders MIT
Splide, Embla Carousel auto-scroll marquee MIT
flutter_custom_carousel builder effect, items before and after, depth order, drag speed, settled callback; deal, wallet, crate and orbit looks BSD-3-Clause
Flutter's CarouselView and ListWheelScrollView Material 3 layouts, wheel BSD-3-Clause

License

MIT. See LICENSE.

Libraries

Every carousel transition in one package.