DxCarousel Class

An interactive component that displays an image collection or custom content in a carousel.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v24.2.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxCarousel :
    DxComponentBase,
    INestedSettingsOwner,
    IDisposable

Remarks

The DevExpress Carousel for Blazor (<DxCarousel>) can display a collection of images or items with custom content in a carousel. The component can operate in bound and unbound modes, supports automatic slide show and loop modes, and allows users to manually navigate through Carousel items.

Run Demo: Carousel

Add a Carousel to a Project

Follow the steps below to add a Carousel component to an application:

1. Use a DevExpress Project Template to create a new Blazor Server or Blazor WebAssembly application. If you use a Microsoft project template or already have a Blazor project, configure your project to incorporate DevExpress Blazor components.
2. Add the following markup to a .razor file: <DxCarousel>…</DxCarousel>.
3. Bind the component to data or create an unbound item collection.
4. Configure user interaction options.
5. Customize component appearance.

.NET 8 and .NET 9 Specifics

Blazor Carousel does not support static render mode. Enable interactivity to use the component in your application. Refer to the following topic for more details: Enable Interactive Render Mode.

Bind to Data (Bound Mode)

Use the Data property to bind the <DxCarousel> component to a data source. Specify ImageSrcField and ImageAltField properties to populate Carousel items with images and corresponding alt attributes from data source fields.

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            ImageSrcField="Source"
            ImageAltField="AlternateText"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

@code {
    List<CarouselData> GetCarouselData() {
        List<CarouselData> result = new List<CarouselData>();
        result.Add(new CarouselData("../images/image1.jpg", "image 1"));
        result.Add(new CarouselData("../images/image2.jpg", "image 2"));
        result.Add(new CarouselData("../images/image3.jpg", "image 3"));
        result.Add(new CarouselData("../images/image4.jpg", "image 4"));

        return result;
    }

    public class CarouselData {
        public string Source { get; set; }
        public string AlternateText { get; set; }

        public CarouselData(string source, string alt) {
            Source = source;
            AlternateText = alt;
        }
    }
}

Item Template

The <DxCarousel> component allows you to customize layout and appearance of Carousel items. Use the ItemTemplate property to specify a common template for all items.

The following code snippet renders images and displays corresponding alternate attributes as image titles:

Razor

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
    <ItemTemplate>
        @{
            var item = context.DataItem as CarouselData;
        }
        <div class="caruselItemContainer">
            <p class="caruselItemCaption">@item?.AlternateText</p>
            <img src="item?.Source" alt="item?.AlternateText" />
        </div>
    </ItemTemplate>
</DxCarousel>

CSS

.caruselItemContainer {
    width: 100%;
    height: 100%;
    position: relative;
}

.caruselItemCaption {
    position: absolute;
    top: 2rem;
    left: 50%;
    transform: translate(-50%, -50%);
    font-size: 2rem;
    font-weight: 700;
}

Unbound Item Collection

The <DxCarousel> component can operate in unbound mode. Populate the component’s <Items>...</Items> tag with DxCarouselItem objects to create an unbound item collection.

The following code snippet populates the Carousel component with different series types of the DxChart<T> component:

Razor

@inject ISalesInfoDataProvider Sales
@* ... *@
    <DxCarousel Width="750px"
                Height="450px"
                SizeMode="Params.SizeMode"
                AllowPagingByClick="false"
                CssClass="demo-carousel-container">
        <Items>
            @foreach(var info in ChartInfos) {
                <DxCarouselItem>
                    <div class="demo-carousel-content">
                        <DxLoadingPanel @bind-Visible="PanelVisible"
                                        IsContentBlocked="true"
                                        ApplyBackgroundShading="false"
                                        IndicatorAreaVisible="true"
                                        Text="Loading...">
                            <DxChart Data="chartsData"
                                     Width="100%"
                                     Height="100%"
                                     Rendered="@ChartRendered">
                                <DxChartTitle Text="@info.Title"></DxChartTitle>
                                @RenderSeries(info.Type, FirstSeriesName)
                                @RenderSeries(info.Type, SecondSeriesName)
                                <DxChartLegend HorizontalAlignment="HorizontalAlignment.Right"/>
                            </DxChart>
                        </DxLoadingPanel>
                    </div>
                </DxCarouselItem>
            }
        </Items>

ChartData

IEnumerable<SaleInfo> chartsData;
int RemainingComponents;

protected override async Task OnInitializedAsync() {
    RemainingComponents = ChartInfos.Count();
    chartsData = await Sales.GetSalesAsync();
}

RenderFragment RenderSeries(string seriesType, string name) {
    switch(seriesType) {
        case "Line":
            return @<DxChartLineSeries Name="@name"
                                       T="SaleInfo"
                                       TArgument="DateTime"
                                       TValue="int"
                                       ArgumentField="si => new DateTime(si.Date.Year, si.Date.Month, 1)"
                                       ValueField="si => si.Amount"
                                       SummaryMethod="Enumerable.Sum"
                                       Filter="si => si.Region == name">
                   </DxChartLineSeries>;
        case "StepLine":
            return @<DxChartStepLineSeries Name="@name"
                                           T="SaleInfo"
                                           TArgument="DateTime"
                                           TValue="int"
                                           ArgumentField="si => new DateTime(si.Date.Year, si.Date.Month, 1)"
                                           ValueField="si => si.Amount"
                                           SummaryMethod="Enumerable.Sum"
                                           Filter="si => si.Region == name">
                   </DxChartStepLineSeries>;
        case "Area":
            return @<DxChartAreaSeries Name="@name"
                                       T="SaleInfo"
                                       TArgument="DateTime"
                                       TValue="int"
                                       ArgumentField="si => new DateTime(si.Date.Year, si.Date.Month, 1)"
                                       ValueField="si => si.Amount"
                                       SummaryMethod="Enumerable.Sum"
                                       Filter="si => si.Region == name">
                   </DxChartAreaSeries>;
        case "StackedSplineArea":
            return @<DxChartStackedSplineAreaSeries Name="@name"
                                                    T="SaleInfo"
                                                    TArgument="DateTime"
                                                    TValue="int"
                                                    ArgumentField="si => new DateTime(si.Date.Year, si.Date.Month, 1)"
                                                    ValueField="si => si.Amount"
                                                    SummaryMethod="Enumerable.Sum"
                                                    Filter="si => si.Region == name">
                   </DxChartStackedSplineAreaSeries>;
    }
    throw new ArgumentException("Incorrect series type");
}

IEnumerable<ChartInfo> ChartInfos = new List<ChartInfo> {
    new("Line", "Line Series"),
    new("StepLine", "Step-Line Series"),
    new("Area", "Area Series"),
    new("StackedSplineArea", "Stacked Spline-Area Series")
};

string FirstSeriesName = "North America";
string SecondSeriesName = "Europe";
bool PanelVisible { get; set; } = true;
void ChartRendered() {
    Interlocked.Decrement(ref RemainingComponents);
    if(RemainingComponents <= 0)
        PanelVisible = false;
}

Run Demo: Carousel

Loop Mode

The <DxCarousel> component allows a user to switch slides (items) from the first item to the last and back. To enable loop navigation between Carousel items, set the LoopNavigationEnabled property to true.

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

Slide Show

Set the SlideShowEnabled property to true to enable the slide show functionality in a <DxCarousel> component. To adjust the time interval between slide changes, use the SlideShowDelay property.

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop"
            SlideShowEnabled="true"
            SlideShowDelay="1500">
</DxCarousel>

You can also use the following properties to specify whether users can stop or pause slide show:

StopSlideShowOnPaging

Specifies whether to stop the slide show on paging.

PauseSlideShowOnHover

Specifies whether to pause the slide show on hover.

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop"
            SlideShowEnabled="true"
            StopSlideShowOnPaging="true"
            PauseSlideShowOnHover="true">
</DxCarousel>

React to Slide Show State Changes

Use the SlideShowState property to specify the current slide show state. To respond to state changes, handle the SlideShowStateChanged event.

The following code snippet obtains the current slide show state and changes it on a button click:

<DxCarousel Width="700px"
            Height="400px"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop"
            SlideShowEnabled="true"
            @bind-SlideShowState="@IsRunning"
            SlideShowDelay="1500"
            SizeMode="SizeMode.Large" />

<DxButton Text="@GetButtonText()"
          RenderStyle="ButtonRenderStyle.Primary"
          RenderStyleMode="ButtonRenderStyleMode.Outline"
          IconCssClass="@GetIconCssClass()"
          Click="SlideShowControl"
          SizeMode="SizeMode.Large" />

@code {
    bool IsRunning { get; set; } = true;

    string GetIconCssClass() {
        return IsRunning ? "oi oi-media-stop" : "oi oi-play-circle";
    }
    string GetButtonText() {
        return IsRunning ? "Stop Slide Show" : "Start Slide Show";
    }

    void SlideShowControl(MouseEventArgs args) {
        IsRunning = !IsRunning;
    }
}

User Interaction Options

The <DxCarousel> component supports multiple options that allow users to switch slides. These options include:

• Navigation buttons
• Keyboard shortcuts
• Swipe gestures
• Mouse wheel and clicks

Users can click the right or left side of the content area to switch slides. Set the AllowPagingByClick property to false to disable paging by mouse clicks.

Enable the AllowMouseWheel property to allow users to switch Carousel slides with the mouse wheel.

Navigation Controls

<DxCarousel> displays navigation controls (buttons and pager) within the content area. Use NavButtonsDisplayMode and PagerDisplayMode properties to specify display modes for navigation controls. AlwaysVisible, VisibleOnHover, and Hidden property values are available.

The following code snippet hides navigation buttons and displays the pager on hover:

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            NavButtonsDisplayMode="CarouselControlsDisplayMode.Hidden"
            PagerDisplayMode="CarouselControlsDisplayMode.VisibleOnHover"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

Keyboard Navigation

The <DxCarousel> component supports keyboard navigation. Users can navigate through Carousel items and stop/start the slideshow.

The following shortcut keys are available:

Shortcut Keys	Description
Tab, Shift+Tab	When the Carousel is focused, moves focus to the next/previous focusable element on a page.
Right Arrow	Navigates to the next Carousel item.
Left Arrow	Navigates to the previous Carousel item.
Shift+Right Arrow	Navigates to the last Carousel item.
Shift+Left Arrow	Navigates to the first Carousel item.
Space	Stops/starts the slide show if SlideShowEnabled is set to true.

Item Navigation in Code

The <DxCarousel> component allows you to navigate through its items in code.

Call the SlideNextAsync() or SlidePreviousAsync() method to navigate to the next or previous Carousel item. Note that the method behavior depends on the LoopNavigationEnabled property value.

The following code snippet navigates between Carousel items on custom button clicks:

<DxCarousel Width="500px"
            Height="300px"
            @ref="carousel"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            NavButtonsDisplayMode="CarouselControlsDisplayMode.Hidden"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

<DxButton IconCssClass="oi oi-arrow-left" Click="OnPreviousButtonClick" />
<DxButton IconCssClass="oi oi-arrow-right" Click="OnNextButtonClick" />

@code {
    DxCarousel carousel;

    async Task OnNextButtonClick(MouseEventArgs args) {
        await carousel.SlideNextAsync();
    }

    async Task OnPreviousButtonClick(MouseEventArgs args) {
        await carousel.SlidePreviousAsync();
    }
}

You can also call the SlideToItemAsync(Int32) method to navigate to the Carousel item with the specified index.

<DxCarousel Width="500px"
            Height="300px"
            @ref="carousel"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

<DxButton Text="First Item" Click="MoveToFirst" />

@code {
    DxCarousel carousel;

    async Task MoveToFirst (MouseEventArgs args) {
        // Navigates to the first item
        await carousel.SlideToItemAsync(0);
    }
}

Active Item Index

Use the ActiveItemIndex property to activate a particular Carousel item programmatically. Handle the ActiveItemIndexChanged event to respond to the property change.

Razor

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            ActiveItemIndex="@CarouselItemIndex"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop"
            ActiveItemIndexChanged="OnActiveItemIndexChanged">
</DxCarousel>

<div>@ItemIndexInfo</div>

DataSource

int CarouselItemIndex { get; set; } = 1;
string ItemIndexInfo { get; set; }

void OnActiveItemIndexChanged(int newItemIndex) {
    CarouselItemIndex = newItemIndex;
    ItemIndexInfo = "You switched to item " + (newItemIndex + 1);
}
List<CarouselData> GetCarouselData() {
    List<CarouselData> result = new List<CarouselData>();
    result.Add(new CarouselData("../images/image1.jpg", "image 1"));
    result.Add(new CarouselData("../images/image2.jpg", "image 2"));
    result.Add(new CarouselData("../images/image3.jpg", "image 3"));
    result.Add(new CarouselData("../images/image4.jpg", "image 4"));

    return result;
}

public class CarouselData {
    public string Src { get; set; }
    public string Alt { get; set; }

    public CarouselData(string src, string alt) {
        Src = src;
        Alt = alt;
    }
}

Customization

This section describes how you can customize the Carousel component’s appearance and behavior.

Size

Use Height and Width properties to specify the size of the <DxCarousel> component. To apply different size modes to navigation controls, specify the component’s SizeMode property.

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            SizeMode="SizeMode.Large"
            ImageSrcField="Source"
            ImageAltField="AlternateText"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

You can also use the ImageSizeMode property to specify how the Carousel component scales an image to fit or fill the content area.

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

Animation

The <DxCarousel> component animates slide (item) changes. Use the AnimationDuration property to specify the animation duration. To disable current animation, set the AnimationEnabled property to false.

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            AnimationDuration="1000"
            LoopNavigationEnabled="true"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

CSS Classes

Assign a CSS class name to the CssClass property to customize the appearance of the <DxCarousel> component.

The following code snippet customizes Carousel borders:

Razor

<DxCarousel Width="500px"
            Height="300px"
            Data="@GetCarouselData()"
            CssClass="carousel-class"
            ImageSizeMode="CarouselImageSizeMode.FillAndCrop">
</DxCarousel>

CSS

.carousel-class {
    border: 3px double black;
    border-radius: 15px;
}

Task-Based Examples

Set a Slide Show Delay for Individual Items

You may need to set a slide show delay for each carousel item individually. Follow the steps below to implement this functionality:

1. Add an interger field (Delay) to your data source and define its values for each carousel item.
2. Declare an interger property (CurrentDelay) and bind it to the SlideShowDelay property.
3. Assign the first item’s Delay field value to the CurrentDelay property in the OnInitialized lifecycle method.
4. Handle the ActiveItemIndexChanged event. In the handler, use the current item’s index to apply the corresponding slide show delay.

<DxCarousel @ref="carousel"
            Height="600px"
            Data="@carouselItems"
            ImageSrcField="ImageSource"
            ImageAltField="ImageAlt"
            SlideShowEnabled="true"
            SlideShowDelay="@CurrentDelay"
            LoopNavigationEnabled="true"
            ActiveItemIndexChanged="OnActiveItemIndexChanged">
</DxCarousel>

@code {
    int CurrentDelay { get; set; }
    DxCarousel carousel;

    protected override void OnInitialized() {
        base.OnInitialized();
        CurrentDelay = carouselItems.First().Delay;
    }
    async void OnActiveItemIndexChanged(int index) {
        if (index != null) {
            CurrentDelay = carouselItems.ElementAt(index).Delay;
        }
    }
    public class CarouselItem {
        public string ImageSource { get; set; }
        public string ImageAlt { get; set; }
        public int Delay { get; set; }
    }
    IEnumerable<CarouselItem> carouselItems = new List<CarouselItem>() {
        new CarouselItem{ImageSource="/images/image1.jpg", ImageAlt="Image 1", Delay=1000},
        new CarouselItem{ImageSource="/images/image2.jpg", ImageAlt="Image 2", Delay=3000},
        new CarouselItem{ImageSource="/images/image3.jpg", ImageAlt="Image 2", Delay=5000},
    };
}

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

Implements

IComponent

IHandleEvent

IHandleAfterRender

IDisposable

Inheritance

Object

ComponentBase

DxComponentBase

DxCarousel