Kebechet.Blazor.Swiper 14.0.6

Blazor.Swiper

A Blazor wrapper for Swiper, built on the framework-agnostic Swiper Element web component. The Swiper bundle is shipped inside the package and auto-registered on startup - no npm build step and no manual <script> tags.

Live storybook - interactive stories for every option.

Installation

dotnet add package Kebechet.Blazor.Swiper

Usage

@using Kebechet.Blazor.Swiper

<Swiper Options="new() { Pagination = true, AllowSlidePrev = true }">
    <SwiperSlide>Slide 1</SwiperSlide>
    <SwiperSlide>Slide 2</SwiperSlide>
    <SwiperSlide>Slide 3</SwiperSlide>
</Swiper>

Styling the shadow-DOM controls (pagination, arrows) is done via Swiper's CSS parts / variables - see the demo.

Any attribute you put on <Swiper> or <SwiperSlide> that isn't a parameter is forwarded to the underlying <swiper-container> / <swiper-slide> element, so class, style and id work as usual.

Options

SwiperOptions is a strongly-typed subset of Swiper's parameters. Nullable members that are left unset keep Swiper's own default.

Observer is off by default

Swiper Element turns its MutationObserver on by default; this wrapper turns it off. With a framework re-rendering slide content - and especially with AutoHeight, whose height writes are themselves DOM mutations - it drives a costly update/height feedback loop. Call Update() explicitly instead when the slide collection changes, or set Observer = true if you want Swiper's behaviour back.

CssMode trades features for smoothness

CssMode = true moves the slider onto the browser's native CSS Scroll Snap API, so scrolling runs on the compositor thread - dramatically smoother for heavy or tall slides. In exchange (these are Swiper's own limitations, not the wrapper's):

• mouse-drag does not work - wheel, trackpad and touch still do, exactly like a native scroller
• Speed is ignored
• transition start/end events do not fire, so use OnSlideChange rather than OnTransitionEnd
• it is not compatible with Loop

Events

<Swiper Options="new() { Pagination = true }"
        OnSlideChange="index => _current = index"
        OnReachEnd="() => _atEnd = true">
    <SwiperSlide>Slide 1</SwiperSlide>
    <SwiperSlide>Slide 2</SwiperSlide>
</Swiper>

Programmatic control

Capture the component with @ref and drive it from C#. ActiveIndex is kept in sync with the underlying Swiper.

<Swiper @ref="_swiper" Options="new() { AllowTouchMove = false }">
    <SwiperSlide>Slide 1</SwiperSlide>
    <SwiperSlide>Slide 2</SwiperSlide>
</Swiper>

<button @onclick="() => _swiper!.SlideNext()">Next</button>

@code {
    private Swiper? _swiper;
}

Every method is a no-op until the component has rendered and its JS module has loaded, so calling one before OnReady does nothing.

Vertical direction needs a height

A vertical Swiper (Direction = SwiperDirection.Vertical) sizes its slides from the <Swiper> element's own height, which defaults to its content height. Give the <Swiper> an explicit height, or it collapses and slides stack:

<Swiper Options="new() { Direction = SwiperDirection.Vertical }" style="height: 300px;">
    ...
</Swiper>

License

MIT