Table of Contents

Class TwCarousel

Namespace
TwBlazor.Components
Assembly
TwBlazor.dll

Represents a carousel that displays one slide (TwCarouselItem) at a time, with optional arrow navigation, slide-picker indicators, swipe gestures, and automatic playback.

public class TwCarousel : TwBlazorComponentBase, IComponent, IHandleEvent, IHandleAfterRender, ITwComponent, IAsyncDisposable
Inheritance
TwCarousel
Implements
Inherited Members

Remarks

Use this component together with TwCarouselItem children, each representing one slide. Only the slide at SelectedIndex is rendered at any given time - there is no slide transition animation, keeping the component's output and behavior simple and predictable.

Constructors

TwCarousel() 

public TwCarousel()

Properties

ActiveItem

Gets the currently selected slide, or null if SelectedIndex is out of range (e.g. no slides have registered yet).

public TwCarouselItem? ActiveItem { get; }

Property Value

TwCarouselItem

AutoPlay

Gets or sets whether the carousel automatically advances to the next slide on a timer. A visible pause/play toggle is rendered whenever this is enabled, so playback can always be stopped (WCAG 2.2.2), and playback also pauses automatically while the pointer or keyboard focus is within the carousel. Default is false.

[Parameter]
public bool AutoPlay { get; set; }

Property Value

bool

AutoPlayInterval

Gets or sets the delay between automatic slide changes when AutoPlay is enabled. Default is 5 seconds.

[Parameter]
public TimeSpan AutoPlayInterval { get; set; }

Property Value

TimeSpan

ButtonColor

Gets or sets the color used for the previous/next arrow buttons and the play/pause toggle. Passed straight through to the underlying TwButton (via TwIcon) as a filled variant, so it needs no bespoke background classes of its own. Default is Light.

[Parameter]
public Color ButtonColor { get; set; }

Property Value

Color

ChildContent

Gets or sets the TwCarouselItem children that make up the carousel's slides.

[Parameter]
public required RenderFragment ChildContent { get; set; }

Property Value

RenderFragment

Color

Gets or sets the accent color used for the active slide indicator dot. If null, the theme's default indicator color is used.

[Parameter]
public Color? Color { get; set; }

Property Value

Color?

EnableSwipeGesture

Gets or sets whether a horizontal touch swipe switches between slides. Default is true.

[Parameter]
public bool EnableSwipeGesture { get; set; }

Property Value

bool

Indicators

Gets or sets custom content to render in place of the default slide-picker indicator dots. The render fragment's context is this TwCarousel instance, giving access to its public API (e.g. GoToSlide(int), SelectedIndex) so custom indicators can drive the carousel. When null (default), the built-in indicator dots are rendered instead, subject to ShowIndicators.

[Parameter]
public RenderFragment<TwCarousel>? Indicators { get; set; }

Property Value

RenderFragment<TwCarousel>

IsAutoPlayManuallyPaused

Gets whether the user has paused automatic playback with the pause/play control. Unlike IsAutoPlayPaused, this ignores the temporary pause while the pointer or keyboard focus is within the carousel, so it is the state a pause/play control should display: the pointer is always over the carousel when its own button is clicked, and using IsAutoPlayPaused there would leave the control showing "paused" no matter how often it was toggled.

public bool IsAutoPlayManuallyPaused { get; }

Property Value

bool

IsAutoPlayPaused

Gets whether automatic playback is currently paused, either because the user toggled the pause control, or because the pointer or keyboard focus is currently within the carousel.

public bool IsAutoPlayPaused { get; }

Property Value

bool

IsFirstSlide

Gets whether the currently selected slide is the first one.

public bool IsFirstSlide { get; }

Property Value

bool

IsLastSlide

Gets whether the currently selected slide is the last one.

public bool IsLastSlide { get; }

Property Value

bool

LeftNavigation

Gets or sets custom content to render in place of the default previous-slide arrow button. The render fragment's context is this TwCarousel instance, giving access to its public API (e.g. PreviousSlide(), NextSlide(), GoToSlide(int), ToggleAutoPlayPaused(), IsAutoPlayPaused) so custom controls can drive the carousel. When null (default), the built-in previous arrow is rendered instead, subject to ShowArrows.

[Parameter]
public RenderFragment<TwCarousel>? LeftNavigation { get; set; }

Property Value

RenderFragment<TwCarousel>

Loop

Gets or sets whether navigating past the last slide wraps around to the first (and vice versa). When false, the arrow buttons are disabled at the boundaries instead. Default is true.

[Parameter]
public bool Loop { get; set; }

Property Value

bool

RightNavigation

Gets or sets custom content to render in place of the default next-slide arrow button. See LeftNavigation for details on the render fragment's context and fallback behavior.

[Parameter]
public RenderFragment<TwCarousel>? RightNavigation { get; set; }

Property Value

RenderFragment<TwCarousel>

SelectedIndex

Gets or sets the index of the currently displayed slide. Supports two-way binding via SelectedIndexChanged.

[Parameter]
public int SelectedIndex { get; set; }

Property Value

int

SelectedIndexChanged

Gets or sets the callback invoked whenever SelectedIndex changes, whether from the arrow buttons, an indicator, a keyboard press, a swipe gesture, or automatic playback.

[Parameter]
public EventCallback<int> SelectedIndexChanged { get; set; }

Property Value

EventCallback<int>

ShowArrows

Gets or sets whether the previous/next arrow buttons are displayed. Default is true.

[Parameter]
public bool ShowArrows { get; set; }

Property Value

bool

ShowIndicators

Gets or sets whether the slide-picker indicator dots are displayed below the carousel. Default is true.

[Parameter]
public bool ShowIndicators { get; set; }

Property Value

bool

Methods

BuildRenderTree(RenderTreeBuilder)

Renders the component to the supplied RenderTreeBuilder.

protected override void BuildRenderTree(RenderTreeBuilder __builder)

Parameters

__builder RenderTreeBuilder

DisposeAsync()

Stops and releases the automatic-playback timer, if one was started.

public ValueTask DisposeAsync()

Returns

ValueTask

GoToSlide(int)

Navigates directly to the slide at index. Does nothing if the index is out of range or already selected.

public Task GoToSlide(int index)

Parameters

index int

The zero-based index of the slide to display.

Returns

Task

NextSlide()

Advances to the next slide, wrapping around to the first slide when Loop is enabled. Does nothing if already on the last slide and Loop is disabled.

public Task NextSlide()

Returns

Task

OnAfterRender(bool)

Starts the automatic-playback timer once, after the first render, when AutoPlay is enabled. The timer's own callback re-checks AutoPlay and IsAutoPlayPaused on every tick, so toggling AutoPlay off later simply stops it from advancing rather than needing to be recreated.

protected override void OnAfterRender(bool firstRender)

Parameters

firstRender bool

PreviousSlide()

Moves to the previous slide, wrapping around to the last slide when Loop is enabled. Does nothing if already on the first slide and Loop is disabled.

public Task PreviousSlide()

Returns

Task

ToggleAutoPlayPaused()

Toggles automatic playback between paused and playing. Exposed publicly so custom LeftNavigation, RightNavigation, or Indicators content can include their own play/pause control. Resuming also clears the current pointer/focus pause: the control is only reachable while the pointer or focus is inside the carousel, so without this the slideshow would stay paused after pressing play until the pointer and focus had left and returned.

public void ToggleAutoPlayPaused()
Edit this page