Lists
Swiper
Swiper (touch slider) shows items in a natively scrolling row: touch swipes keep the platform's momentum, and it can be moved with buttons, dots, drag, keyboard, wheel, code or autoplay. Unlike the Carousel it does not page through slides; it can snap to items, fit a responsive number of them, scroll vertically, and follows the ARIA carousel pattern.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
































Navigation
























Multiple items
SnapAlign
Vertical
Dots
AutoPlay
Interaction & motion
Public API
Load more
Accessibility
- AriaLabel names the region.
- ItemAriaLabelFormat names unlabelled items ({0} position, {1} count; "{0} of {1}" by default).
- DotsAriaLabel names the dots group; DotAriaLabel prefixes each dot's page number.
- NextAriaLabel / PrevAriaLabel and PlayButtonAriaLabel / PauseButtonAriaLabel name the buttons.












Cascading parameters
Color
External Icons
















Size
Style & Class












RTL
CSS variables
The public custom properties this component reads off its root, for what no parameter covers.
Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property:
set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it,
or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.
BitSwiper CSS variables
| Name | Default value | Description |
|---|---|---|
| --bit-Swiper-gap | 0 | Space between the items. The Gap parameter wins over it, and VisibleItemsCount takes it into account. |
| --bit-Swiper-peek | 0 | Room at both ends of the swiper the neighboring items peek into. The Peek parameter wins over it. |
| --bit-Swiper-vertical-height | 25 spacing units | Height of a vertical swiper that was not given one through Style or a class. |
| --bit-Swiper-focus-color | --bit-clr-pri-focus | Color of every keyboard focus indicator: the root, the buttons and the dots. The Color parameter wins over it. |
| --bit-Swiper-button-color | --bit-clr-fg-pri | Glyph color of the next/prev and play/pause buttons, and the text of templated dots. The Color parameter wins over it. |
| --bit-Swiper-button-hover-color | --bit-clr-fg-pri-hover | Glyph color of those buttons on hover. The Color parameter wins over it. |
| --bit-Swiper-button-background | transparent | Background of the next/prev strips, for buttons that have to stand out over busy items. |
| --bit-Swiper-button-hover-background | The rest background | Background of the next/prev strips on hover. |
| --bit-Swiper-button-opacity | 0.7 | Opacity of the buttons at rest; hover and focus bring them to 1. Keep it high enough for a 3:1 contrast. |
| --bit-Swiper-button-width | 10% | Width of the next/prev strips (their height on a vertical swiper), never below the 24px pointer target. |
| --bit-Swiper-button-size | spacing(3) | Glyph size of the next/prev buttons. The Size parameter wins over it. |
| --bit-Swiper-dot-size | spacing(1.25) | Diameter of a dot. Its hit area never drops below the 24px WCAG target. The Size parameter wins over it. |
| --bit-Swiper-dot-current-width | The dot size | Width of the current dot; a larger value turns it into a pill. |
| --bit-Swiper-dot-radius | The full radius | Corner radius of a dot. |
| --bit-Swiper-dot-gap | What keeps a 24px target per dot | Space between the dots. A smaller value lets their hit areas overlap. |
| --bit-Swiper-dot-color | The primary border color | Fill of a dot, which keeps a 3:1 contrast against the background by default. |
| --bit-Swiper-dot-hover-color | The primary border hover color | Fill of a dot on hover. |
| --bit-Swiper-dot-current-color | --bit-clr-pri | Fill of the current dot (text color of a templated one). The Color and Accent parameters win over it. |
| --bit-Swiper-dot-current-hover-color | --bit-clr-pri-hover | Fill of the current dot on hover. The Color and Accent parameters win over it. |
| --bit-Swiper-dots-margin | 1.25 spacing units | Space between the items and the row of dots. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitSwiper 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. An explicit value wins over the --bit-Swiper-dot-current-* variables; left unset, the current dot is primary unless they say otherwise. |
| AnimationDuration | double | 0.5 | Sets the duration of the scrolling animation in seconds (the default value is 0.5). A value of 0 moves the items at once. |
| AutoPlay | bool | false | Enables/disables the auto scrolling of the items. It pauses while hovered, focused or in a hidden tab, and starts paused under prefers-reduced-motion unless ForceAnimation is set. |
| 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 item towards the first one. |
| ChildContent | RenderFragment? | null | Items of the swiper. |
| Classes | BitSwiperClassStyles? | null | The custom CSS classes for the different parts of the swiper. |
| Color | BitColor? | null | The general color of the swiper, applied to the dot of the current page, the next/prev and play/pause buttons and the focus indicators. An explicit value wins over the --bit-Swiper-* focus, button and current-dot color variables; left unset, the swiper keeps its defaults unless they say otherwise. |
| DefaultItem | int | 1 | The item (1 based, like GoTo) the swiper starts on when it first renders. Values outside of the range of the swiper are clamped to its first or last item. |
| DotAriaLabel | string | Slide | The accessible label of a dot of the swiper, 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 swiper. |
| DotTemplate | RenderFragment<int>? | null | The custom content of a dot of the swiper, receiving the zero based index of the page the dot navigates to. |
| DragThreshold | int | 5 | The distance (in pixels) the pointer has to travel over the swiper before it starts dragging it, instead of the press staying a click. |
| Gap | string? | null | The space between the items of the swiper (any CSS length, for example 1rem), which VisibleItemsCount takes into account. |
| HideNextPrev | bool | false | Hides the Next/Prev buttons of the BitSwiper. Each button also hides itself at the end it cannot move any further towards. |
| ItemAriaLabelFormat | string? | null | The accessible label of an item of the swiper, as a composite format string whose {0} is the 1 based position of the item and whose {1} is the number of items ("{0} of {1}" by default). Used for items without their own AriaLabel, and announced when the swiper moves to the item. |
| NextAriaLabel | string? | null | The accessible label of the next button of the swiper (the default value is "Next slide"). |
| NextIcon | BitIconInfo? | null | Gets or sets the icon to display in the next navigation button using custom CSS classes for external icon libraries. Takes precedence over NextIconName when both are set. |
| NextIconName | string? | null | Gets or sets the name of the icon to display in the next navigation button from the built-in Fluent UI icons. |
| NoDrag | bool | false | Disables dragging the swiper with the mouse. A touch swipe is the browser's own scrolling of the region and is not taken away. |
| NoKeyboard | bool | false | Removes the swiper from the tab sequence and turns off its keyboard navigation. |
| OnChange | EventCallback<int> | The event that will be called with the zero based index of the item the swiper came to stand on, however it was moved. | |
| OnReachEnd | EventCallback | The event that will be called each time the swiper is moved to its end, not when a resize or removed items put it there, and once per set of items for a swiper everything fits in, which is where more items are loaded. | |
| OnReachStart | EventCallback | The event that will be called each time the swiper is moved back to its start (not for the start it is first laid out on, nor when a resize or a change of its items puts it there). | |
| PauseButtonAriaLabel | string | Stop automatic slide show | The accessible label of the play/pause button while the auto scrolling is running. |
| PauseIcon | BitIconInfo? | null | Gets or sets the icon of the play/pause button while the auto scrolling is running, using custom CSS classes for external icon libraries. |
| PauseIconName | string? | null | Gets or sets 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 swiper. |
| PauseOnHover | bool | true | Pauses the auto scrolling while the pointer is over the swiper. |
| Peek | string? | null | The room (any CSS length, for example 2rem) kept at both ends of the swiper, which the neighboring items peek into. VisibleItemsCount fits its items between the two, and the items settle against it. Each end is capped at a quarter of the swiper. |
| PlayButtonAriaLabel | string | Start automatic slide show | The accessible label of the play/pause button while the auto scrolling is paused. |
| PlayIcon | BitIconInfo? | null | Gets or sets the icon of the play/pause button while the auto scrolling is paused, using custom CSS classes for external icon libraries. |
| PlayIconName | string? | null | Gets or sets the name of the icon of the play/pause button while the auto scrolling is paused, from the built-in Fluent UI icons. |
| PrevAriaLabel | string? | null | The accessible label of the previous button of the swiper (the default value is "Previous slide"). |
| PrevIcon | BitIconInfo? | null | Gets or sets the icon to display in the previous navigation button using custom CSS classes for external icon libraries. Takes precedence over PrevIconName when both are set. |
| PrevIconName | string? | null | Gets or sets the name of the icon to display in the previous navigation button from the built-in Fluent UI icons. |
| Rewind | bool | false | Wraps the manual navigation around: moving on from the end goes back to the start and the other way around. It covers the next/prev buttons (which then stay visible at both ends), the arrow keys and GoNext/GoPrev; the wheel and dragging still stop at the ends. |
| ScrollItemsCount | int | 1 | Number of items that is going to be changed on navigation, which is the step of the buttons, the arrow keys and the mouse wheel. |
| ShowDots | bool | false | Renders the navigation dots below the items of the swiper, one per screenful of it. |
| ShowPlayPause | bool | false | Renders a play/pause button next to the dots, so the auto scrolling can be stopped and started again. |
| ShowScrollbar | bool | false | Leaves the scrollbar of the swiper visible, which is hidden by default. |
| Size | BitSize? | null | The size of the dots and of the next/prev buttons of the swiper. An explicit value wins over --bit-Swiper-dot-size and --bit-Swiper-button-size; left unset, the swiper is medium unless they say otherwise. |
| SnapAlign | BitScrollSnapAlign? | null | Settles the swiper on an item instead of leaving it wherever the scrolling ran out, and chooses where that item comes to rest. |
| StopOnInteraction | bool | false | Stops the auto scrolling as soon as the swiper is navigated by hand. |
| StopOnLastSlide | bool | false | Stops the auto scrolling at the end of the swiper instead of rewinding to its start. |
| Styles | BitSwiperClassStyles? | null | The custom CSS styles for the different parts of the swiper. |
| Vertical | bool | false | Stacks the items vertically, so the swiper scrolls up and down instead of left and right. |
| VisibleItemsCount | int? | null | Number of items that is visible in the swiper, which sizes the items accordingly. Without it the items keep whatever size they were given. |
| 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 swiper with the wheel of the mouse (or with a two finger scroll on a trackpad). |
BitSwiper public members
| Name | Type | Default value | Description |
|---|---|---|---|
| CurrentIndex | int | The zero based index of the item the swiper is currently standing on. | |
| CurrentPage | int | The zero based index of the screenful (page) the swiper is currently showing. | |
| IsAtStart | bool | Whether the swiper is scrolled all the way to its start. | |
| IsAtEnd | bool | Whether the swiper is scrolled all the way to its end. | |
| IsPaused | bool | Whether the auto scrolling has been paused through Pause or the play/pause button. | |
| IsPlaying | bool | Whether the auto scrolling is currently running. | |
| ItemsCount | int | The number of items of the swiper. | |
| PagesCount | int | The number of screenfuls (pages) the items of the swiper take up. | |
| GoNext | Task | Navigates to the next swiper item. | |
| GoPrev | Task | Navigates to the previous swiper item. | |
| GoTo | Task | Navigates to the given swiper item number (1 based). | |
| GoToPage | Task | Navigates to the given swiper page number (1 based), a page being one screenful of the swiper. | |
| GoToStart | Task | Navigates to the start of the swiper. | |
| GoToEnd | Task | Navigates to the end of the swiper. | |
| 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 swiper again and reports where it stands. |
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. |
| Disabled | bool | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| 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. |
| 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. |
BitSwiperClassStyles properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Root | string? | null | Custom CSS classes/styles for the root element of the BitSwiper. |
| Container | string? | null | Custom CSS classes/styles for the scrolling container of the BitSwiper. |
| Item | string? | null | Custom CSS classes/styles for the items of the BitSwiper. |
| CurrentItem | string? | null | Custom CSS classes/styles for the item the swiper is currently standing on. |
| Buttons | string? | null | Custom CSS classes/styles for the next/prev buttons of the BitSwiper. |
| ButtonIcons | string? | null | Custom CSS classes/styles for the icons of the next/prev buttons of the BitSwiper. |
| NextButton | string? | null | Custom CSS classes/styles for the next button of the BitSwiper. |
| NextButtonIcon | string? | null | Custom CSS classes/styles for the icon of the next button of the BitSwiper. |
| PrevButton | string? | null | Custom CSS classes/styles for the previous button of the BitSwiper. |
| PrevButtonIcon | string? | null | Custom CSS classes/styles for the icon of the previous button of the BitSwiper. |
| DotsContainer | string? | null | Custom CSS classes/styles for the dots container of the BitSwiper. |
| Dots | string? | null | Custom CSS classes/styles for the dot elements of the BitSwiper. |
| CurrentDot | string? | null | Custom CSS classes/styles for the current dot element of the BitSwiper. |
| PlayPauseButton | string? | null | Custom CSS classes/styles for the play/pause button of the BitSwiper. |
| PlayPauseButtonIcon | string? | null | Custom CSS classes/styles for the icon of the play/pause button of the BitSwiper. |
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. |
BitScrollSnapAlign enum
| Name | Value | Description |
|---|---|---|
| None | 0 | The children carry no snap position of their own. |
| Start | 1 | Each child comes to rest at the start of the pane. |
| Center | 2 | Each child comes to rest in the middle of the pane. |
| End | 3 | Each child comes to rest at the end of the pane. |
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
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.