Carousel - bit BlazorUI

Accent color

Carousel (slideshow) displays a set of items across sliding pages. It can be navigated with its built-in buttons and dots, by dragging, with the keyboard or the mouse wheel, programmatically, or automatically with autoplay. It shows one or several items at a time (adapting that to its own width), scrolls horizontally or vertically, cross-fades instead of sliding, and follows the carousel pattern of the ARIA authoring practices: a labelled carousel region of labelled slides, real buttons for every control, off-screen slides taken out of the reading and tab order, and a rotation that stops as soon as the pointer or the keyboard focus reaches it.

ForceAnimation (whole page)

Usage

Basic

<style>
    .number {
        position: absolute;
        top: 0.75rem;
        padding: 0.75rem;
        font-size: 0.75rem;
        color: #D7D7D7;
    }

    .image {
        width: 100%;
        height: 100%;
    }
</style>

<BitCarousel AriaLabel="Landscape photos">
    <BitCarouselItem>
        <div class="number">1 / 4</div>
        <img class="image" alt="Aurora" src="img1.jpg">
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">2 / 4</div>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">3 / 4</div>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">4 / 4</div>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
    </BitCarouselItem>
</BitCarousel>

The basic carousel shows one slide at a time and renders its default chrome: the next/prev buttons over the sides and the navigation dots below the slides. It can also be dragged with the pointer and, since it is focusable, navigated with the arrow keys and the Home/End keys. Give the carousel an AriaLabel that describes its content, so assistive technologies can announce what the carousel region holds.

1 / 4

2 / 4

3 / 4

4 / 4

InfiniteScrolling

<style>
    .image {
        width: 100%;
        height: 100%;
    }

    .text-title {
        position: absolute;
        bottom: 3.4375rem;
        width: 100%;
        font-size: 0.9375rem;
        text-align: center;
        color: #FFFFFF;
    }

    .text-description {
        position: absolute;
        bottom: 1.875rem;
        width: 100%;
        font-size: 0.6875rem;
        text-align: center;
        color: #FFFFFF;
    }
</style>

<BitCarousel InfiniteScrolling>
    <BitCarouselItem>
        <img class="image" alt="Aurora" src="img1.jpg" />
        <div class="text-title">Aurora</div>
        <div class="text-description">This is Aurora and it's fantastic</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
        <div class="text-title">Beautiful Mountain</div>
        <div class="text-description">This is a Beautiful Mountain and it's gorgeous</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
        <div class="text-title">Forest In The Valley</div>
        <div class="text-description">This is a Forest In The Valley and it's beautiful</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
        <div class="text-title">Road Among The Mountains</div>
        <div class="text-description">This is a Road Among The Mountains and it's amazing</div>
    </BitCarouselItem>
</BitCarousel>

The InfiniteScrolling parameter makes the carousel loop: the first slide follows the last one and the last one precedes the first, so both navigation buttons stay available at all times instead of hiding at the ends.

Aurora

This is Aurora and it's fantastic

Beautiful Mountain

This is a Beautiful Mountain and it's gorgeous

Forest In The Valley

This is a Forest In The Valley and it's beautiful

Road Among The Mountains

This is a Road Among The Mountains and it's amazing

HideDots

<BitCarousel HideDots>
    <BitCarouselItem>
        <div class="number">1 / 4</div>
        <img class="image" alt="Aurora" src="img1.jpg" />
        <div class="text-title">Aurora</div>
        <div class="text-description">This is Aurora and it's fantastic</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">2 / 4</div>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
        <div class="text-title">Beautiful Mountain</div>
        <div class="text-description">This is a Beautiful Mountain and it's gorgeous</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">3 / 4</div>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
        <div class="text-title">Forest In The Valley</div>
        <div class="text-description">This is a Forest In The Valley and it's beautiful</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">4 / 4</div>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
        <div class="text-title">Road Among The Mountains</div>
        <div class="text-description">This is a Road Among The Mountains and it's amazing</div>
    </BitCarouselItem>
</BitCarousel>

The HideDots parameter removes the navigation dots below the slides, leaving only the next/prev buttons (which the HideNextPrev parameter removes in the same way for a fully chromeless carousel).

1 / 4

Aurora

This is Aurora and it's fantastic

2 / 4

Beautiful Mountain

This is a Beautiful Mountain and it's gorgeous

3 / 4

Forest In The Valley

This is a Forest In The Valley and it's beautiful

4 / 4

Road Among The Mountains

This is a Road Among The Mountains and it's amazing

Public API

<BitCarousel HideNextPrev @ref="carousel" OnChange="v => currentPage = v">
    <BitCarouselItem>
        <div class="number">1 / 4</div>
        <img class="image" alt="Aurora" src="img1.jpg" />
        <div class="text-title">Aurora</div>
        <div class="text-description">This is Aurora and it's fantastic</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">2 / 4</div>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
        <div class="text-title">Beautiful Mountain</div>
        <div class="text-description">This is a Beautiful Mountain and it's gorgeous</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">3 / 4</div>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
        <div class="text-title">Forest In The Valley</div>
        <div class="text-description">This is a Forest In The Valley and it's beautiful</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">4 / 4</div>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
        <div class="text-title">Road Among The Mountains</div>
        <div class="text-description">This is a Road Among The Mountains and it's amazing</div>
    </BitCarouselItem>
</BitCarousel>

<BitButton OnClick="GoPrev">&lt; Prev</BitButton>
<BitButton OnClick="GoNext">Next &gt;</BitButton>

<BitButton OnClick="GoTo">GoTo</BitButton>
<BitNumberField @bind-Value="number" Min="1" Max="4" Mode="BitSpinButtonMode.Compact" />

<div>Current page: @currentPage</div>
@code {
    private int number = 1;
    private int currentPage;
    private BitCarousel carousel = default!;
    
    private async Task GoNext()
    {
        await carousel.GoNext();
    }
    
    private async Task GoPrev()
    {
        await carousel.GoPrev();
    }
    
    private async Task GoTo()
    {
        await carousel.GoTo(number);
    }
}

The carousel can be driven entirely from application code through a @ref to it: GoNext, GoPrev and GoTo (1 based) navigate the slides, Pause, Resume and TogglePlay drive the auto scrolling, and Refresh measures the carousel again after something else moved the ground under it. The CurrentPage (zero based), PagesCount, ItemsCount, IsPlaying and IsPaused members report where it stands, and OnChange fires with the index of the page it moved to. This example hides the built-in buttons and replaces them with its own.

1 / 4

Aurora

This is Aurora and it's fantastic

2 / 4

Beautiful Mountain

This is a Beautiful Mountain and it's gorgeous

3 / 4

Forest In The Valley

This is a Forest In The Valley and it's beautiful

4 / 4

Road Among The Mountains

This is a Road Among The Mountains and it's amazing

Current page: 0

AutoPlay

<BitCarousel HideNextPrev InfiniteScrolling AutoPlay AutoPlayInterval="2500">
    <BitCarouselItem>
        <div class="number">1 / 4</div>
        <img class="image" alt="Aurora" src="img1.jpg" />
        <div class="text-title">Aurora</div>
        <div class="text-description">This is Aurora and it's fantastic</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">2 / 4</div>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
        <div class="text-title">Beautiful Mountain</div>
        <div class="text-description">This is a Beautiful Mountain and it's gorgeous</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">3 / 4</div>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
        <div class="text-title">Forest In The Valley</div>
        <div class="text-description">This is a Forest In The Valley and it's beautiful</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">4 / 4</div>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
        <div class="text-title">Road Among The Mountains</div>
        <div class="text-description">This is a Road Among The Mountains and it's amazing</div>
    </BitCarouselItem>
</BitCarousel>

<BitCarousel InfiniteScrolling AutoPlay AutoPlayInterval="2000" ShowPlayPause StopOnInteraction>
    <BitCarouselItem>
        <div class="number">1 / 4</div>
        <img class="image" alt="Aurora" src="img1.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">2 / 4</div>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">3 / 4</div>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">4 / 4</div>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
    </BitCarouselItem>
</BitCarousel>

<BitCarousel AutoPlay AutoPlayReverse InfiniteScrolling HideNextPrev Style="height: 100px">
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
</BitCarousel>

<BitCarousel AutoPlay StopOnLastSlide HideNextPrev Style="height: 100px">
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
</BitCarousel>

The AutoPlay parameter rotates the slides on its own at the AutoPlayInterval. The rotation pauses while the pointer rests over the carousel or the keyboard focus is inside it (PauseOnHover / PauseOnFocus, both on by default) and while the page sits in a background tab, and resumes when they leave.

1 / 4

Aurora

This is Aurora and it's fantastic

2 / 4

Beautiful Mountain

This is a Beautiful Mountain and it's gorgeous

3 / 4

Forest In The Valley

This is a Forest In The Valley and it's beautiful

4 / 4

Road Among The Mountains

This is a Road Among The Mountains and it's amazing

The ShowPlayPause parameter renders a play/pause button next to the dots so the rotation can be stopped and started by hand (which WCAG asks of any auto-moving content), and StopOnInteraction stops it for good as soon as the carousel is navigated manually. Pause, Resume and TogglePlay do the same from code, and IsPaused / IsPlaying report the state.

1 / 4

2 / 4

3 / 4

4 / 4

The AutoPlayReverse parameter plays the rotation backwards, from the last slide towards the first one.

StopOnLastSlide stops the rotation on the last page instead of rewinding to the first one, which only applies to a carousel that does not scroll infinitely, since an infinite one never reaches an end.

Multiple items

<style>
    .item {
        text-align: center;
        color: black;
        border: 1px solid blue;
        background-color: lightblue;
    }

    .item div {
        transform: translate(0, 80%);
    }
</style>

<BitCarousel Style="height: 100px" VisibleItemsCount="3" ScrollItemsCount="3">
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>5</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>6</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>7</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>8</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>9</div></BitCarouselItem>
</BitCarousel>

<BitCarousel Style="height: 100px" VisibleItemsCount="3" ScrollItemsCount="1">
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>5</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>6</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>7</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>8</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>9</div></BitCarouselItem>
</BitCarousel>

The VisibleItemsCount parameter lays several slides out side by side, and ScrollItemsCount sets how many of them a navigation moves at a time, so the carousel can page through its items in groups or advance them one by one. The two of them together decide where the carousel stops: a page is one step of it, which is what a dot stands for and what OnChange reports, so a carousel that shows three slides and moves them one at a time gets a dot per slide rather than one per screenful, and its dots keep up with it.

Three at a time, moved three at a time (three pages of three slides):

The same nine slides shown three at a time but moved one at a time, which stops in seven places instead of three. The slides the next step shares with the current one stay where they are instead of being thrown out and animated back in.

Gap

<style>
    .gap-item {
        height: 100%;
        box-sizing: border-box;
    }
</style>

<BitCarousel Style="height: 100px" VisibleItemsCount="3" ScrollItemsCount="1" Gap="1rem" InfiniteScrolling>
    <BitCarouselItem><div class="item gap-item">1</div></BitCarouselItem>
    <BitCarouselItem><div class="item gap-item">2</div></BitCarouselItem>
    <BitCarouselItem><div class="item gap-item">3</div></BitCarouselItem>
    <BitCarouselItem><div class="item gap-item">4</div></BitCarouselItem>
    <BitCarouselItem><div class="item gap-item">5</div></BitCarouselItem>
    <BitCarouselItem><div class="item gap-item">6</div></BitCarouselItem>
</BitCarousel>

The Gap parameter puts space (any CSS length) between the slides of a multi-item carousel. The space is carved out of the room each slide occupies, so the pages keep lining up no matter how many slides are visible.

Vertical

<BitCarousel Vertical Style="height: 200px" InfiniteScrolling>
    <BitCarouselItem>
        <div class="number">1 / 4</div>
        <img class="image" alt="Aurora" src="img1.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">2 / 4</div>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">3 / 4</div>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">4 / 4</div>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
    </BitCarouselItem>
</BitCarousel>

The Vertical parameter stacks the slides over the height of the carousel, so it scrolls up and down instead of left and right: the navigation buttons move to the top and bottom edges and the up/down arrow keys take over the navigation.

1 / 4

2 / 4

3 / 4

4 / 4

Fade

<BitCarousel Fade InfiniteScrolling>
    <BitCarouselItem>
        <div class="number">1 / 4</div>
        <img class="image" alt="Aurora" src="img1.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">2 / 4</div>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">3 / 4</div>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <div class="number">4 / 4</div>
        <img class="image" alt="Road among the mountains" src="img4.jpg" />
    </BitCarouselItem>
</BitCarousel>

The Fade parameter cross-fades the slides in place instead of sliding them, for the classic slideshow look. A fading carousel shows exactly one slide at a time.

1 / 4

2 / 4

3 / 4

4 / 4

Interaction

<BitCarousel Wheel NoDrag InfiniteScrolling Style="height: 100px" VisibleItemsCount="3" ScrollItemsCount="1">
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>5</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>6</div></BitCarouselItem>
</BitCarousel>

The way the carousel is operated by hand is configurable: NoDrag turns off dragging it with the pointer, NoKeyboard takes it out of the tab sequence and turns off the arrow key navigation (arrow keys, Home and End), Wheel navigates it with the mouse wheel (or a trackpad scroll), and DragThreshold sets how far a drag has to travel before it counts. A drag that travels further across the carousel than along it is left alone, so scrolling a page by dragging over a carousel never flips its slides; and a wheel moves the carousel forwards when it is scrolled away from the reader (down, or right), whichever way its slides are laid out.

This carousel is navigated with the mouse wheel and cannot be dragged:

Animation

<style>
    .item {
        text-align: center;
        color: black;
        border: 1px solid blue;
        background-color: lightblue;
    }

    .item div {
        transform: translate(0, 80%);
    }
</style>

<BitCarousel Style="height: 100px" AnimationDuration="1.5" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
</BitCarousel>

<BitCarousel Style="height: 100px" AnimationDuration="0" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
</BitCarousel>

The AnimationDuration parameter sets how long the slide transition takes, in seconds (0.5 by default). A value of 0 moves the slides at once, with no animation at all, and the same duration also drives the cross-fade speed of the Fade effect.

Slow transition (1.5 seconds):

No animation (0 seconds):

DefaultPage

<BitCarousel Style="height: 100px" DefaultPage="3">
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>5</div></BitCarouselItem>
</BitCarousel>

The DefaultPage parameter sets the page (1 based, like GoTo) the carousel shows when it first renders. It is only read during the first layout, so changing it afterwards does not move the carousel (use GoTo for that), and values outside of the range of the carousel are clamped to its first or last page.

Responsive

<BitCarousel Style="height: 100px"
             VisibleItemsCount="4"
             ScrollItemsCount="4"
             InfiniteScrolling
             ResponsiveOptions="@([new() { Breakpoint = 640, VisibleItemsCount = 1, ScrollItemsCount = 1 },
                                   new() { Breakpoint = 960, VisibleItemsCount = 2, ScrollItemsCount = 2 },
                                   new() { Breakpoint = 1280, VisibleItemsCount = 3, ScrollItemsCount = 3 }])">
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>5</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>6</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>7</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>8</div></BitCarouselItem>
</BitCarousel>

The ResponsiveOptions parameter adapts VisibleItemsCount and ScrollItemsCount to the width of the carousel. Each option applies while the carousel is no wider than its Breakpoint (in pixels) and the narrowest matching one wins, so the options can be listed in any order; a carousel wider than every breakpoint keeps the counts of its own parameters. The width that is matched is the width of the carousel itself rather than of the window, so the same carousel adapts to the room it is given inside a sidebar and across a full width page.

Resize the window (or this panel) to watch the number of slides change:

Dots

<style>
    .thumb-dot {
        width: 3rem;
        height: 2rem;
        padding: 0;
        overflow: hidden;
        border-radius: 0.25rem;
        opacity: 0.5;
    }

    .thumb-dot-current {
        opacity: 1;
        outline: 2px solid var(--bit-clr-pri);
    }

    .thumb {
        width: 100%;
        height: 100%;
        object-fit: cover;
    }
</style>

<BitCarousel Style="height: 100px" InfiniteScrolling>
    <DotTemplate Context="index"><span>@(index + 1)</span></DotTemplate>
    <ChildContent>
        <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
        <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
        <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
        <BitCarouselItem Class="item"><div>4</div></BitCarouselItem>
    </ChildContent>
</BitCarousel>

<BitCarousel InfiniteScrolling
             Classes="@(new() { Dots = "thumb-dot", CurrentDot = "thumb-dot-current" })">
    <DotTemplate Context="index">
        <img class="thumb" alt="" src="@($"img{index + 1}.jpg")" />
    </DotTemplate>
    <ChildContent>
        <BitCarouselItem>
            <img class="image" alt="Aurora" src="img1.jpg" />
        </BitCarouselItem>
        <BitCarouselItem>
            <img class="image" alt="Beautiful mountain" src="img2.jpg" />
        </BitCarouselItem>
        <BitCarouselItem>
            <img class="image" alt="Forest in the valley" src="img3.jpg" />
        </BitCarouselItem>
        <BitCarouselItem>
            <img class="image" alt="Road among the mountains" src="img4.jpg" />
        </BitCarouselItem>
    </ChildContent>
</BitCarousel>

The DotTemplate parameter replaces the content of a dot, receiving the zero based index of the page it navigates to, so the row below the slides can carry page numbers, thumbnails, or anything else. A dot that holds content is laid out around it instead of being drawn as the default circle, and it keeps the accessible label (DotAriaLabel) and the current page marker the carousel gives it either way.

Numbered dots:

Thumbnails of the slides they navigate to:

Accessibility

<BitCarousel AutoPlay
             ShowPlayPause
             InfiniteScrolling
             AriaLabel="Landscape photos"
             ItemAriaLabelFormat="Photo {0} of {1}"
             DotAriaLabel="Photo"
             DotsAriaLabel="Choose a photo to display"
             GoLeftAriaLabel="Next photo"
             GoRightAriaLabel="Previous photo"
             PlayButtonAriaLabel="Start the photo slide show"
             PauseButtonAriaLabel="Stop the photo slide show">
    <BitCarouselItem AriaLabel="Aurora over a frozen lake">
        <img class="image" alt="Aurora" src="img1.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Beautiful mountain" src="img2.jpg" />
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Forest in the valley" src="img3.jpg" />
    </BitCarouselItem>
</BitCarousel>

The carousel follows the carousel pattern of the ARIA authoring practices out of the box: its root is a region marked as a carousel, every slide is a group marked as a slide, the slides that are scrolled out of the view are taken out of the reading and the tab order, all of the controls are real buttons that point at the slides they move with aria-controls, and the play/pause button is the first thing the keyboard reaches so the motion can be stopped before anything else. The text of all of that is yours to set:

AriaLabel names the carousel region, which is what a screen reader announces on the way in.
ItemAriaLabelFormat names the slides that carry no label of their own ("{0} of {1}" by default, where {0} is the position of the slide and {1} the number of slides); a slide that deserves a better name takes an AriaLabel of its own.
DotsAriaLabel names the group of dots and DotAriaLabel prefixes each one of them, which is followed by the number of the page it navigates to.
GoLeftAriaLabel and GoRightAriaLabel name the navigation buttons, which otherwise are labelled after what they do (which flips with the direction of the carousel).
PlayButtonAriaLabel and PauseButtonAriaLabel name the rotation control in each of its two states.

Color

<BitCarousel Color="BitColor.Primary" Style="height: 72px" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
</BitCarousel>

<BitCarousel Color="BitColor.Success" Style="height: 72px" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
</BitCarousel>

<BitCarousel Color="BitColor.Warning" Style="height: 72px" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
</BitCarousel>

<BitCarousel Color="BitColor.Error" Style="height: 72px" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
</BitCarousel>

The Color parameter offers the general colors of the theme for the chrome of the carousel: it colors the dot of the current page and the navigation buttons. The Accent parameter is its lighter-weight sibling that only offers the primary/secondary/tertiary/transparent kinds for the current dot.

Primary

Success

Warning

Error

External Icons

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css" />

<div>FontAwesome (circle-arrow icons):</div>
<BitCarousel InfiniteScrolling
             GoLeftIcon="@BitIconInfo.Fa("solid circle-arrow-right")"
             GoRightIcon="@BitIconInfo.Fa("solid circle-arrow-left")">
    <BitCarouselItem>
        <img class="image" alt="Aurora" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img1.jpg" />
        <div class="text-title">Aurora</div>
        <div class="text-description">This is Aurora and it's fantastic</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Beautiful mountain" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img2.jpg" />
        <div class="text-title">Beautiful Mountain</div>
        <div class="text-description">This is a Beautiful Mountain and it's gorgeous</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Forest in the valley" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img3.jpg" />
        <div class="text-title">Forest In The Valley</div>
        <div class="text-description">This is a Forest In The Valley and it's beautiful</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Road among the mountains" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img4.jpg" />
        <div class="text-title">Road Among The Mountains</div>
        <div class="text-description">This is a Road Among The Mountains and it's amazing</div>
    </BitCarouselItem>
</BitCarousel>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.min.css" />

<div>Bootstrap Icons (arrow-left-circle / arrow-right-circle):</div>
<BitCarousel InfiniteScrolling
             GoLeftIcon="@BitIconInfo.Bi("arrow-right-circle")"
             GoRightIcon="@BitIconInfo.Bi("arrow-left-circle")">
    <BitCarouselItem>
        <img class="image" alt="Aurora" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img1.jpg" />
        <div class="text-title">Aurora</div>
        <div class="text-description">This is Aurora and it's fantastic</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Beautiful mountain" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img2.jpg" />
        <div class="text-title">Beautiful Mountain</div>
        <div class="text-description">This is a Beautiful Mountain and it's gorgeous</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Forest in the valley" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img3.jpg" />
        <div class="text-title">Forest In The Valley</div>
        <div class="text-description">This is a Forest In The Valley and it's beautiful</div>
    </BitCarouselItem>
    <BitCarouselItem>
        <img class="image" alt="Road among the mountains" src="_content/Bit.BlazorUI.Demo.Client.Core/images/carousel/img4.jpg" />
        <div class="text-title">Road Among The Mountains</div>
        <div class="text-description">This is a Road Among The Mountains and it's amazing</div>
    </BitCarouselItem>
</BitCarousel>

Use icons from external libraries like FontAwesome, Material Icons, and Bootstrap Icons with the GoLeftIcon and GoRightIcon parameters.

FontAwesome (circle-arrow icons):

Aurora

This is Aurora and it's fantastic

Beautiful Mountain

This is a Beautiful Mountain and it's gorgeous

Forest In The Valley

This is a Forest In The Valley and it's beautiful

Road Among The Mountains

This is a Road Among The Mountains and it's amazing

Bootstrap Icons (arrow-left-circle / arrow-right-circle):

Aurora

This is Aurora and it's fantastic

Beautiful Mountain

This is a Beautiful Mountain and it's gorgeous

Forest In The Valley

This is a Forest In The Valley and it's beautiful

Road Among The Mountains

This is a Road Among The Mountains and it's amazing

Size

<BitCarousel Size="BitSize.Small" Style="height: 72px" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
</BitCarousel>

<BitCarousel Size="BitSize.Medium" Style="height: 72px" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
</BitCarousel>

<BitCarousel Size="BitSize.Large" Style="height: 72px" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>1</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>2</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>3</div></BitCarouselItem>
</BitCarousel>

The Size parameter offers three sizes for the chrome of the carousel: the dots and the navigation buttons.

Small

Medium

Large

Style & Class

<style>
    .custom-item {
        color: white;
        display: grid;
        place-items: center;
        background: linear-gradient(135deg, #5843be, #9787e5);
    }
</style>

<BitCarousel Style="height: 100px; border-radius: 0.5rem; overflow: hidden"
             InfiniteScrolling
             Styles="@(new() { Buttons = "color: white; background-color: rgba(0,0,0,0.35); width: 2.5rem;",
                               CurrentDot = "background-color: mediumpurple;" })"
             Classes="@(new() { Item = "custom-item" })">
    <BitCarouselItem><div>1</div></BitCarouselItem>
    <BitCarouselItem><div>2</div></BitCarouselItem>
    <BitCarouselItem><div>3</div></BitCarouselItem>
    <BitCarouselItem><div>4</div></BitCarouselItem>
</BitCarousel>

Besides the Style and Class parameters of the root element, the Styles and Classes parameters customize every part of the carousel: its container, its items and the ones of them currently on screen (Item and CurrentItem), the navigation buttons and their icons, the dots and the current dot, and the play/pause button and its icon.

RTL

<style>
    .item {
        text-align: center;
        color: black;
        border: 1px solid blue;
        background-color: lightblue;
    }

    .item div {
        transform: translate(0, 80%);
    }
</style>

<BitCarousel Style="height: 100px" Dir="BitDir.Rtl" VisibleItemsCount="3" ScrollItemsCount="1" InfiniteScrolling>
    <BitCarouselItem Class="item"><div>یک</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>دو</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>سه</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>چهار</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>پنج</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>شیش</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>هفت</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>هشت</div></BitCarouselItem>
    <BitCarouselItem Class="item"><div>نه</div></BitCarouselItem>
</BitCarousel>

In right-to-left mode the carousel lays its slides out and navigates from right to left, and the roles of the two navigation buttons flip accordingly.

یک

دو

سه

چهار

پنج

شیش

هفت

هشت

نه

API

BitCarousel parameters

Name	Type	Default value	Description
Accent	BitColorKind?	null	Specifies the accent color kind of the component, which colors the dot of the current page. Color takes precedence over it when both are set.
AnimationDuration	double	0.5	Sets the duration of the scrolling animation in seconds (the default value is 0.5).
AutoPlay	bool	false	Enables/disables the auto scrolling of the slides.
AutoPlayInterval	double	2000	Sets the interval of the auto scrolling in milliseconds (the default value is 2000).
AutoPlayReverse	bool	false	Plays the auto scrolling backwards, from the last slide towards the first one.
ChildContent	RenderFragment?	null	Items of the carousel.
Classes	BitCarouselClassStyles?	null	The custom CSS classes for the different parts of the carousel.
Color	BitColor?	null	The general color of the carousel, applied to the dot of the current page and the next/prev and play/pause buttons.
DefaultPage	int	1	The page (1 based, like GoTo) the carousel shows when it first renders. Values outside of the range of the carousel are clamped to its first or last page.
DotAriaLabel	string	Slide	The accessible label of a dot of the carousel, followed by the number of the page it navigates to.
DotsAriaLabel	string	Choose slide to display	The accessible label of the dots container of the carousel.
DotTemplate	RenderFragment<int>?	null	The custom content of a dot of the carousel, receiving the zero based index of the page the dot navigates to. A dot that holds content is laid out around it instead of being drawn as the default circle.
DragThreshold	int	20	The distance (in pixels) the pointer has to travel over the carousel before it moves to another page.
Fade	bool	false	Cross-fades the slides in place instead of sliding them. A fading carousel shows exactly one slide at a time.
Gap	string?	null	The space between the slides of the carousel (any CSS length, for example 1rem).
GoLeftAriaLabel	string?	null	The accessible label of the go to left button. When not set, the button is labelled after what it does (next or previous slide, depending on the direction).
GoLeftIcon	BitIconInfo?	null	Gets or sets the icon for the go to left button using custom CSS classes for external icon libraries. Takes precedence over GoLeftIconName when both are set.
GoLeftIconName	string?	null	Gets or sets the name of the icon for the go to left button from the built-in Fluent UI icons.
GoRightAriaLabel	string?	null	The accessible label of the go to right button. When not set, the button is labelled after what it does (previous or next slide, depending on the direction).
GoRightIcon	BitIconInfo?	null	Gets or sets the icon for the go to right button using custom CSS classes for external icon libraries. Takes precedence over GoRightIconName when both are set.
GoRightIconName	string?	null	Gets or sets the name of the icon for the go to right button from the built-in Fluent UI icons.
HideDots	bool	false	Hides the Dots indicator at the bottom of the BitCarousel. The dots are also left out when everything fits on a single page.
HideNextPrev	bool	false	Hides the Next/Prev buttons of the BitCarousel. Each button also hides itself at the end it cannot move any further towards, unless InfiniteScrolling is enabled.
InfiniteScrolling	bool	false	If enabled the carousel items will navigate in an infinite loop (first item comes after last item and last item comes before first item).
ItemAriaLabelFormat	string?	null	The accessible label of a slide of the carousel, as a composite format string whose {0} is the 1 based position of the slide and whose {1} is the number of slides ("{0} of {1}" when not set). It is only used for the slides that were not given an AriaLabel of their own.
NoDrag	bool	false	Disables dragging the carousel with the pointer.
NoKeyboard	bool	false	Removes the carousel from the tab sequence and turns off its keyboard navigation (arrow keys, Home and End).
OnChange	EventCallback<int>		The event that will be called on carousel page navigation. The provided value is the zero based index of the page the carousel moved to.
PauseButtonAriaLabel	string	Stop automatic slide show	The accessible label of the play/pause button while the auto scrolling is running.
PauseIcon	BitIconInfo?	null	The icon of the play/pause button while the auto scrolling is running, using custom CSS classes for external icon libraries. Takes precedence over PauseIconName.
PauseIconName	string?	null	The name of the icon of the play/pause button while the auto scrolling is running, from the built-in Fluent UI icons.
PauseOnFocus	bool	true	Pauses the auto scrolling while the keyboard focus is inside the carousel.
PauseOnHover	bool	true	Pauses the auto scrolling while the pointer is over the carousel.
PlayButtonAriaLabel	string	Start automatic slide show	The accessible label of the play/pause button while the auto scrolling is paused.
PlayIcon	BitIconInfo?	null	The icon of the play/pause button while the auto scrolling is paused, using custom CSS classes for external icon libraries. Takes precedence over PlayIconName.
PlayIconName	string?	null	The name of the icon of the play/pause button while the auto scrolling is paused, from the built-in Fluent UI icons.
ResponsiveOptions	IEnumerable<BitCarouselResponsiveOption>?	null	Adapts VisibleItemsCount and ScrollItemsCount to the width of the carousel. Each option applies while the carousel is no wider than its Breakpoint, and the narrowest matching one wins.
ScrollItemsCount	int	1	Number of items that is going to be changed on navigation. It is clamped to VisibleItemsCount, and a non-infinite carousel moves by fewer items near its ends so its first and last pages always stay full. Together with VisibleItemsCount it also decides where the carousel stops, which is what the dots stand for and what OnChange reports.
ShowPlayPause	bool	false	Renders a play/pause button next to the dots, so the auto scrolling can be stopped and started again. Only rendered while AutoPlay is enabled.
Size	BitSize?	null	The size of the dots and of the next/prev buttons of the carousel.
StopOnInteraction	bool	false	Stops the auto scrolling as soon as the carousel is navigated by hand. Once stopped this way the rotation only comes back through Resume or the play/pause button.
StopOnLastSlide	bool	false	Stops the auto scrolling on the last page instead of rewinding to the first one. It has no effect while InfiniteScrolling is enabled.
Styles	BitCarouselClassStyles?	null	The custom CSS styles for the different parts of the carousel.
Vertical	bool	false	Stacks the slides vertically, so the carousel scrolls up and down instead of left and right.
VisibleItemsCount	int	1	Number of items that is visible in the carousel.
Wheel	bool	false	Navigates the carousel with the wheel of the mouse (or with a two finger scroll on a trackpad).

BitCarousel public members

Name	Type	Description
CurrentPage	int	The zero based index of the page the carousel is currently showing.
ItemsCount	int	The number of items (slides) of the carousel.
PagesCount	int	The number of pages of the carousel.
IsPlaying	bool	Whether the auto scrolling is currently running.
IsPaused	bool	Whether the auto scrolling has been paused through Pause or the play/pause button.
GoNext	Task	Navigates to the next carousel item.
GoPrev	Task	Navigates to the previous carousel item.
GoTo	Task	Navigates to the given carousel page number (1 based).
Pause	void	Pauses the AutoPlay if enabled.
Resume	void	Resumes the AutoPlay if enabled.
TogglePlay	void	Pauses the AutoPlay when it is running, and resumes it when it is paused.
Refresh	Task	Measures the carousel again and lays its slides out accordingly.

BitComponentBase parameters

Name	Type	Default value	Description
AriaLabel	string?	null	Gets or sets the accessible label for the component, used by assistive technologies.
Class	string?	null	Gets or sets the CSS class name(s) to apply to the rendered element.
Dir	BitDir?	null	Gets or sets the text directionality for the component's content.
ForceAnimation	bool	false	Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes	Dictionary<string, object>	new Dictionary<string, object>()	Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters.
Id	string?	null	Gets or sets the unique identifier for the component's root element.
IsEnabled	bool	true	Gets or sets a value indicating whether the component is enabled and can respond to user interaction.
Style	string?	null	Gets or sets the CSS style string to apply to the rendered element.
TabIndex	string?	null	Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility	BitVisibility	BitVisibility.Visible	Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name	Type	Default value	Description
UniqueId	Guid	Guid.NewGuid()	Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement	ElementReference		Gets the reference to the root HTML element associated with this component.

BitCarouselItem properties

A single slide of the BitCarousel.

Name	Type	Default value	Description
ChildContent	RenderFragment?	null	The content of the carousel item (slide).
Index	int	0	The zero based position of this item among the items of its carousel (read-only, assigned by the carousel).

BitCarouselResponsiveOption properties

The layout a BitCarousel takes while it is no wider than a given breakpoint. A member that is left unset keeps the value of the matching parameter of the carousel.

Name	Type	Default value	Description
Breakpoint	double	0	The largest width (in pixels) of the carousel this option applies to.
VisibleItemsCount	int?	null	The number of items that is visible in the carousel while this option applies.
ScrollItemsCount	int?	null	The number of items a navigation moves while this option applies.

BitCarouselClassStyles properties

The custom CSS classes and styles of the different parts of the BitCarousel.

Name	Type	Default value	Description
Root	string?	null	Custom CSS classes/styles for the root element of the BitCarousel.
Container	string?	null	Custom CSS classes/styles for the container of the BitCarousel.
Item	string?	null	Custom CSS classes/styles for the items (slides) of the BitCarousel.
CurrentItem	string?	null	Custom CSS classes/styles for the items (slides) of the BitCarousel that are currently on screen.
Buttons	string?	null	Custom CSS classes/styles for the next/prev buttons of the BitCarousel.
ButtonIcons	string?	null	Custom CSS classes/styles for the icons of the next/prev buttons of the BitCarousel.
GoLeftButton	string?	null	Custom CSS classes/styles for the go to left button of the BitCarousel.
GoLeftButtonIcon	string?	null	Custom CSS classes/styles for the icon of the go to left button of the BitCarousel.
GoRightButton	string?	null	Custom CSS classes/styles for the go to right button of the BitCarousel.
GoRightButtonIcon	string?	null	Custom CSS classes/styles for the icon of the go to right button of the BitCarousel.
DotsContainer	string?	null	Custom CSS classes/styles for the dots container of the BitCarousel.
Dots	string?	null	Custom CSS classes/styles for the dot elements of the BitCarousel.
CurrentDot	string?	null	Custom CSS classes/styles for the current dot element of the BitCarousel.
PlayPauseButton	string?	null	Custom CSS classes/styles for the play/pause button of the BitCarousel.
PlayPauseButtonIcon	string?	null	Custom CSS classes/styles for the icon of the play/pause button of the BitCarousel.

BitIconInfo properties

Name	Type	Default value	Description
Name	string?	null	Gets or sets the name of the icon.
BaseClass	string?	null	Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty.
Prefix	string?	null	Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty.

BitColorKind enum

Name	Value	Description
Primary	0	The primary color kind.
Secondary	1	The secondary color kind.
Tertiary	2	The tertiary color kind.
Transparent	3	The transparent color kind.

BitColor enum

Name	Value	Description
Primary	0	Primary general color.
Secondary	1	Secondary general color.
Tertiary	2	Tertiary general color.
Info	3	Info general color.
Success	4	Success general color.
Warning	5	Warning general color.
SevereWarning	6	SevereWarning general color.
Error	7	Error general color.
PrimaryBackground	8	Primary background color.
SecondaryBackground	9	Secondary background color.
TertiaryBackground	10	Tertiary background color.
PrimaryForeground	11	Primary foreground color.
SecondaryForeground	12	Secondary foreground color.
TertiaryForeground	13	Tertiary foreground color.
PrimaryBorder	14	Primary border color.
SecondaryBorder	15	Secondary border color.
TertiaryBorder	16	Tertiary border color.

BitSize enum

Name	Value	Description
Small	0	The small size.
Medium	1	The medium size.
Large	2	The large size.

BitVisibility enum

Name	Value	Description
Visible	0	The content of the component is visible.
Hidden	1	The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed	2	The component is hidden (display:none).

BitDir enum

Name	Value	Description
Ltr	0	Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl	1	Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto	2	Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

You can give us your feedback through our GitHub repo by filing a new Issue or starting a new Discussion.

Or you can review / edit this page on GitHub.

Or you can review / edit this component on GitHub.