# salla-slider (https://docs.salla.dev/twilight/react/web-components/salla-slider) {/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */} Swiper-based slider for banners, product carousels, testimonials and product image galleries with thumbnails. Use it whenever a theme needs a swipeable list of items. Put the slides as children of one `
`; each child becomes a slide. For `type="thumbs"`, add the thumbnails as children of a `
`. Important: the arrows and the pagination find their elements through the host `id`, so set an `id` on `salla-slider` if you use `show-controls` or `pagination`. Set `static-when-single` to skip the slider when there is only one slide. Accessibility: the arrow buttons are real `button` elements with `aria-label`s ("Previous Slide" and "Next Slide"), and pagination bullets are clickable. ## Use it [#use-it] In HTML or JSX, use the tag `` with the **Attribute** names below. In React, the wrapper takes the **Property** names (camelCase). This component has a native React version. Use it instead of the raw tag: ```tsx import { SallaSlider } from '@salla.sa/twilight-components-react'; ``` ## Try it [#try-it] ## Example [#example] ```tsx import { SallaSlider } from '@salla.sa/twilight-components-react'; export function Example() { return (
Slide 1
Slide 2
Slide 3
 ); } ``` ```html
Slide 1
Slide 2
Slide 3
 ``` ```tsx import { SallaSlider } from '@salla.sa/twilight-components-react'; export function Example() { return (
); } ``` ```html
``` ## Properties [#properties] | Property | Attribute | Description | Type | Default | | -------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------- | | `arrowsCentered` | `arrows-centered` | Adds the `s-slider-v-centered` class to the host. The arrow position is styled by the theme CSS. | `boolean` | `false` | | `autoHeight` | `auto-height` | Lets the slider height follow the height of the active slide. | `boolean` | `false` | | `autoPlay` | `auto-play` | Starts autoplay with a 10 second delay between slides. Pass a Swiper `autoplay` options object through `slider-config` to use a different delay. | `boolean` | `false` | | `blockSubtitle` | `block-subtitle` | Subtitle shown under the title. It is inserted as HTML. Only shown when `block-title` is set. | `string` | `''` | | `blockTitle` | `block-title` | Title text shown above the slider as an `h2`. When empty, no title is rendered. | `string` | `''` | | `centered` | `centered` | Centers the active slide (Swiper `centeredSlides`). | `boolean` | `false` | | `controlsOuter` | `controls-outer` | Adds the `s-slider-controls-outer` class so the theme CSS can place the arrows outside the slider. | `boolean` | `false` | | `direction` | `direction` | Reading direction of the slider, `rtl` or `ltr`. Defaults to `document.documentElement.dir`. | `string` | | | `displayAllUrl` | `display-all-url` | URL for a "Display all" link shown beside the arrows. When empty, no link is rendered. | `string` | `''` | | `gridThumbs` | `grid-thumbs` | Adds the `s-slider-grid-thumbs` class to the thumbs wrapper so the theme CSS can show the thumbs as a grid. Only used with `type="thumbs"`. | `boolean` | `false` | | `listenToThumbnailsOption` | `listen-to-thumbnails-option` | When true, the slider jumps to a slide when a product option of type `thumbnail` or `color` is changed (the `product-options::change` event). Each slide needs `data-img-id` (the gallery image id) and `data-slid-index` (the slide index) attributes. Read once at load. | `boolean` | `false` | | `loop` | `loop` | Run slider in loop, Don't use it for slides with custom components inside it, because it may cause re-render issue | `boolean` | `false` | | `pagination` | `pagination` | Shows clickable pagination bullets. Only works when the slider host has an `id` attribute. | `boolean` | `false` | | `showControls` | `show-controls` | Shows the previous and next arrow buttons. They only work when the slider host has an `id` attribute. | `boolean` | `true` | | `showThumbsControls` | `show-thumbs-controls` | Shows the previous and next arrows of the thumbs slider. Only used with `type="thumbs"`, and the arrows only work when the slider host has an `id` attribute. | `boolean` | `true` | | `sliderConfig` | `slider-config` | Extra Swiper parameters, as an object or a JSON string. They are merged over the component defaults and the `type` preset, so they win. See [https://swiperjs.com/swiper-api#parameters](https://swiperjs.com/swiper-api#parameters). | `any` | | | `slidesPerView` | `slides-per-view` | Value passed to Swiper `slidesPerView`: `auto` or a number of slides shown at once. | `string` | `"auto"` | | `staticWhenSingle` | `static-when-single` | When enabled and there is exactly one slide in the `items` slot, render without initializing Swiper (single slide mode). | `boolean` | `false` | | `thumbsConfig` | `thumbs-config` | Extra Swiper parameters for the thumbs slider, as an object or a JSON string, merged over its defaults. Only used with `type="thumbs"` and when the `thumbs` slot has content. See [https://swiperjs.com/swiper-api#parameters](https://swiperjs.com/swiper-api#parameters). | `any` | | | `type` | `type` | Preset for the slider. `carousel` shows slides at their natural width; `fullscreen` is a vertical slider with mouse wheel navigation; `thumbs` is a main slider synced with a thumbnails slider from the `thumbs` slot (typical for product galleries); `testimonials` shows 1 slide (2 from 1024px); `blog` loops with centered slides; `fullwidth` uses a slower parallax transition. `default`, `hero` and an empty value apply no preset (`hero` and `default` only add a CSS class). | `"" \| "blog" \| "carousel" \| "default" \| "fullscreen" \| "fullwidth" \| "hero" \| "testimonials" \| "thumbs"` | `''` | | `vertical` | `vertical` | Makes the main slider vertical from 768px viewport width and up (it is horizontal on smaller screens). The slider container is rendered with `dir="ltr"` when this is on. | `boolean` | `false` | | `verticalThumbs` | `vertical-thumbs` | Lays out the thumbs slider vertically from 768px viewport width and up. Only used with `type="thumbs"`. | `boolean` | `false` | ### `sliderConfig` example [#sliderconfig-example] ```ts let slider = document.querySelector('salla-slider'); slider.sliderConfig = { slidesPerView: 1, spaceBetween: 30, } ``` ### `thumbsConfig` example [#thumbsconfig-example] ```ts let slider = document.querySelector('salla-slider'); slider.thumbsConfig = { slidesPerView: 3, spaceBetween: 10, } ``` ## Events [#events] Listen with `addEventListener`, or the `on` prop of the React wrapper (for example `onModalBack`). | Event | Description | Detail | | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ------ | | `afterInit` | Fires once Swiper has been initialized. `event.detail` is the Swiper instance. | `any` | | `reachBeginning` | Fires when the slider reaches the first slide. `event.detail` is the Swiper instance. | `any` | | `reachEnd` | Fires when the slider reaches the last slide. `event.detail` is the Swiper instance. | `any` | | `slideChange` | Fires when the active slide changes. `event.detail` is the Swiper instance. | `any` | | `slideChangeTransitionEnd` | Fires after the animation to another slide (next or previous) ends. `event.detail` is the Swiper instance. | `any` | | `slideChangeTransitionStart` | Fires when the animation to another slide (next or previous) starts. `event.detail` is the Swiper instance. | `any` | | `slideNextTransitionEnd` | Same as `slideChangeTransitionEnd` but for forward movement only. `event.detail` is the Swiper instance. | `any` | | `slideNextTransitionStart` | Same as `slideChangeTransitionStart` but for forward movement only. `event.detail` is the Swiper instance. | `any` | | `slidePrevTransitionEnd` | Same as `slideChangeTransitionEnd` but for backward movement only. `event.detail` is the Swiper instance. | `any` | | `slidePrevTransitionStart` | Same as `slideChangeTransitionStart` but for backward movement only. `event.detail` is the Swiper instance. | `any` | | `sliderMove` | Fires while the user drags the slider with a finger or mouse. `event.detail` is the Swiper instance. | `any` | | `sliderTransitionEnd` | Fires after a transition ends. `event.detail` is the Swiper instance. | `any` | | `sliderTransitionStart` | Fires when a transition starts. `event.detail` is the Swiper instance. | `any` | | `touchSliderEnd` | Fires when the user releases the slider after touching it. `event.detail` is the Swiper instance. | `any` | | `touchSliderMove` | Fires when the user touches the slider and moves their finger. `event.detail` is the Swiper instance. | `any` | | `touchSliderStart` | Fires when the user touches the slider. `event.detail` is the Swiper instance. | `any` | ## Methods [#methods] Call these on the element or a React ref. ### `getSlides() => Promise` [#getslides--promiseany] Returns the slide elements of the main slider. Returns `Promise`: A Promise that resolves to the Swiper `slides` array, or `undefined` before the slider has initialized. ### `getThumbsSlides() => Promise` [#getthumbsslides--promiseany] Returns the slide elements of the thumbs slider. Returns `Promise`: A Promise that resolves to the thumbs Swiper `slides` array, or `undefined` if there is no thumbs slider. ### `getThumbsUpdateSize() => Promise` [#getthumbsupdatesize--promiseany] Recalculates the size of the thumbs slider container. Does nothing if there is no thumbs slider. Returns `Promise`: A Promise that resolves when the update is done. ### `slideNext(speed?: number, runCallbacks?: boolean) => Promise` [#slidenextspeed-number-runcallbacks-boolean--promisevoid] Slides to the next slide. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | ### `slideNextLoop(speed?: number, runCallbacks?: boolean) => Promise` [#slidenextloopspeed-number-runcallbacks-boolean--promisevoid] Same as `slideNext`, for sliders with `loop` on. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | ### `slidePrev(speed?: number, runCallbacks?: boolean) => Promise` [#slideprevspeed-number-runcallbacks-boolean--promisevoid] Slides to the previous slide. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | ### `slidePrevLoop(speed?: number, runCallbacks?: boolean) => Promise` [#slideprevloopspeed-number-runcallbacks-boolean--promisevoid] Same as `slidePrev`, for sliders with `loop` on. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | ### `slideReset(speed?: number, runCallbacks?: boolean) => Promise` [#slideresetspeed-number-runcallbacks-boolean--promisevoid] Returns the slider to the position of the currently active slide. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | ### `slideTo(index: number, speed?: number, runCallbacks?: boolean) => Promise` [#slidetoindex-number-speed-number-runcallbacks-boolean--promiseany] Slides to the slide at the given index. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `index` | `number` | Slide index, starting at 0. | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | Returns `Promise`: A Promise that resolves to what Swiper `slideTo` returns. ### `slideToClosest(speed?: number, runCallbacks?: boolean) => Promise` [#slidetoclosestspeed-number-runcallbacks-boolean--promisevoid] Moves the slider to the closest slide position. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | ### `slideToLoop(index: number, speed?: number, runCallbacks?: boolean) => Promise` [#slidetoloopindex-number-speed-number-runcallbacks-boolean--promisevoid] Same as `slideTo`, for sliders with `loop` on: slides to the slide whose real index (the index in the original slides) matches. Does nothing until the slider has initialized. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `index` | `number` | Real slide index, starting at 0. | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | ### `sliderInit() => Promise` [#sliderinit--promiseany] Calls Swiper `init()` on the main slider. Does nothing until the slider has initialized. Returns `Promise`: A Promise that resolves when it has finished. ### `sliderInstance() => Promise` [#sliderinstance--promiseany] Returns the Swiper instance of the main slider so you can use the Swiper API directly. Returns `Promise`: A Promise that resolves to the Swiper instance, or `undefined` before the slider has initialized. ### `thumbsSlideTo(index: number, speed?: number, runCallbacks?: boolean) => Promise` [#thumbsslidetoindex-number-speed-number-runcallbacks-boolean--promiseany] Slides the thumbs slider to the slide at the given index. Does nothing if there is no thumbs slider. | Parameter | Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | `index` | `number` | Slide index, starting at 0. | | `speed` | `number` | Transition duration in milliseconds. | | `runCallbacks` | `boolean` | Set to `false` to skip the transition events. Defaults to `true`. | Returns `Promise`: A Promise that resolves to what Swiper `slideTo` returns. ### `thumbsSliderInit() => Promise` [#thumbssliderinit--promiseany] Calls Swiper `init()` on the thumbs slider. Only call it with `type="thumbs"` after the slider has initialized, otherwise it throws. Returns `Promise`: A Promise that resolves when it has finished. ### `thumbsSliderInstance() => Promise` [#thumbssliderinstance--promiseany] Returns the Swiper instance of the thumbs slider (only exists with `type="thumbs"`). Returns `Promise`: A Promise that resolves to the thumbs Swiper instance, or `undefined`. ### `thumbsSliderUpdate() => Promise` [#thumbssliderupdate--promiseany] Runs Swiper `update()` on the thumbs slider. Only call it with `type="thumbs"` after the slider has initialized, otherwise it throws. Returns `Promise`: A Promise that resolves when the update is done. ### `thumbsSliderUpdateSlides() => Promise` [#thumbssliderupdateslides--promiseany] Runs Swiper `updateSlides()` on the thumbs slider. Only call it with `type="thumbs"` after the slider has initialized, otherwise it throws. Returns `Promise`: A Promise that resolves when the update is done. ### `update() => Promise` [#update--promisevoid] Recalculates the slider (size, slides, progress and classes). Call it after you add or remove slides in JavaScript, or after showing a slider that was hidden. Does nothing until the slider has initialized. ### `updateAutoHeight(speed?: number) => Promise` [#updateautoheightspeed-number--promisevoid] Recalculates the slider height to match the active slide. Useful with `auto-height`. Does nothing until the slider has initialized. | Parameter | Type | Description | | --------- | -------- | ------------------------------------ | | `speed` | `number` | Transition duration in milliseconds. | ### `updateProgress() => Promise` [#updateprogress--promisevoid] Recalculates the slider progress value. Does nothing until the slider has initialized. ### `updateSize() => Promise` [#updatesize--promiseany] Recalculates the size of the slider container. Call it after the container size changed. Does nothing until the slider has initialized. Returns `Promise`: A Promise that resolves when the update is done. ### `updateSlides() => Promise` [#updateslides--promisevoid] Recalculates the number of slides and their offsets. Call it after you add or remove slides in JavaScript. Does nothing until the slider has initialized. ### `updateSlidesClasses() => Promise` [#updateslidesclasses--promisevoid] Updates the active, previous and next classes on the slides and pagination bullets. Does nothing until the slider has initialized. ## Slots [#slots] | Slot | Description | | --------- | --------------------------------------------------------------------------------------- | | (default) | Default slot, rendered inside the slider container before the slides. | | `items` | Slider items. Wrap them in one `
`; each child becomes a slide. | | `thumbs` | Thumbs slider items, used when `type="thumbs"`. Wrap them in one `
`. | ## Related [#related] Used inside: [``](https://docs.salla.dev/twilight/react/web-components/salla-attachment-view), [``](https://docs.salla.dev/twilight/react/web-components/salla-cart-coupons), [``](https://docs.salla.dev/twilight/react/web-components/salla-gifting), [``](https://docs.salla.dev/twilight/react/web-components/salla-loyalty), [``](https://docs.salla.dev/twilight/react/web-components/salla-loyalty-panel), [``](https://docs.salla.dev/twilight/react/web-components/salla-loyalty-program), [``](https://docs.salla.dev/twilight/react/web-components/salla-multiple-bundle-product-options-modal), [``](https://docs.salla.dev/twilight/react/web-components/salla-multiple-bundle-product-slider), [``](https://docs.salla.dev/twilight/react/web-components/salla-offer), [``](https://docs.salla.dev/twilight/react/web-components/salla-offer-modal), [``](https://docs.salla.dev/twilight/react/web-components/salla-products-slider), [``](https://docs.salla.dev/twilight/react/web-components/salla-reviews), [``](https://docs.salla.dev/twilight/react/web-components/salla-reward-details).