# Carousel
**Also known as:** SlideShow
## Description
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.
## 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. The Xs to Xxl variants override it responsively, based on the width of the carousel itself. |
| VisibleItemsCountXs | `int?` | null | Number of visible items in the extra small breakpoint (from 0 up). |
| VisibleItemsCountSm | `int?` | null | Number of visible items in the small breakpoint (from 600px up). |
| VisibleItemsCountMd | `int?` | null | Number of visible items in the medium breakpoint (from 960px up). |
| VisibleItemsCountLg | `int?` | null | Number of visible items in the large breakpoint (from 1280px up). |
| VisibleItemsCountXl | `int?` | null | Number of visible items in the extra large breakpoint (from 1920px up). |
| VisibleItemsCountXxl | `int?` | null | Number of visible items in the extra extra large breakpoint (from 2560px up). |
| Wheel | `bool` | false | Navigates the carousel with the wheel of the mouse (or with a two finger scroll on a trackpad). |
| 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. |
## Public Members
| Name | Type | Default Value | 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. |
| 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. |
## Enums
### 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. |
## Sub Classes
### 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. |
## Examples
\n**Basic**:
```razor
```
\n**InfiniteScrolling**:
```razor
```
\n**HideDots**:
```razor
```
\n**Public API**:
```razor
< Prev
Next >
GoTo
```
\n**Multiple items**:
```razor
```
\n**Responsive**:
```razor
```
\n**Gap**:
```razor
```
\n**Vertical**:
```razor
```
\n**Fade**:
```razor
```
\n**Interaction**:
```razor
```
\n**Animation**:
```razor
```
\n**DefaultPage**:
```razor
```
\n**Dots**:
```razor
@(index + 1)
```
\n**Thumbnails**:
```razor
```
\n**Color**:
```razor
```
\n**External Icons**:
```razor
```
\n**Size**:
```razor
```
\n**Style & Class**:
```razor
```
\n**RTL**:
```razor
```
1 / 4
2 / 4
3 / 4
4 / 4
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
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
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: @currentPage
```
```csharp
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);
}
```
\n**AutoPlay**:
```razor
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
1 / 4
2 / 4
3 / 4
4 / 4
1
2
3
4
1
2
3
4
1
2
3
4
5
6
7
8
9
1
2
3
4
5
6
7
8
9
1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8
1
2
3
4
5
6
1 / 4
2 / 4
3 / 4
4 / 4
1 / 4
2 / 4
3 / 4
4 / 4
1
2
3
4
5
6
1
2
3
4
1
2
3
4
1
2
3
4
5
1
2
3
4
@for (int i = 0; i < 4; i++)
{
var index = i;
}
```
```csharp
private int thumbsCurrentPage;
private BitCarousel thumbsCarousel = default!;
```
\n**Accessibility**:
```razor
1
2
3
1
2
3
1
2
3
1
2
3
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
1
2
3
1
2
3
1
2
3
یک
دو
سه
چهار
پنج
شیش
هفت
هشت
نه