Carousel

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.

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.

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).

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.

Current page: 0

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.

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.

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.

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.

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:

The responsive variants of VisibleItemsCount (Xs, Sm, Md, Lg, Xl and Xxl) are the shorthand for the common case: each one applies from its breakpoint upwards (Xs from 0, Sm from 600, Md from 960, Lg from 1280, Xl from 1920 and Xxl from 2560 pixels, the shared breakpoints of bit BlazorUI), and the base VisibleItemsCount covers everything below the smallest one that is set (so nothing at all when Xs is set). They are matched against the width of the carousel itself too, and a matching ResponsiveOptions entry takes precedence over them. The carousel below changes from one visible slide up to four:

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.

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.

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.

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:

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):

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.

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:

A strip of thumbnails outside of the carousel can drive it through its public API: clicking a thumbnail navigates with GoTo, and the OnChange event keeps the highlighted thumbnail in sync no matter how the carousel was moved (buttons, dragging, the keyboard or autoplay). Compare it with the DotTemplate of the previous section, which puts the thumbnails into the dots of the carousel itself.

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:

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.

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

FontAwesome (circle-arrow icons):

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

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

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.

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.