Skip to content

vadimkorr/svelte-carousel

Repository files navigation

svelte-carousel

svelte-carousel

npm npm
GitHub repo GitHub followers

The awesome carousel component for Svelte 3

Demo

Installation

yarn add svelte-carousel
npm install svelte-carousel

Import component

<script>
  import Carousel from 'svelte-carousel'
  // ...
</script>

SvelteKit support

There are several things to keep in mind when svelte-carousel is used with SvelteKit. This is because svelte-carousel is a client-side library and depends on document and window. See more in SvelteKit FAQ.

  1. Install svelte-carousel as a dev dependency. Why as a dev dependency?
yarn add svelte-carousel -D
npm install svelte-carousel -D
  1. Extend kit in svelte.config.js to include the vite property
const config = {
  // existing props
  kit: {
    // existing props
    vite: {
      optimizeDeps: {
        include: ['lodash.get', 'lodash.isequal', 'lodash.clonedeep']
      }
      // plugins: []
    }
  }
}
  1. Import and use it:
<script>
  import Carousel from 'svelte-carousel';
  import { browser } from '$app/environment';

  let carousel; // for calling methods of the carousel instance
  
  const handleNextClick = () => {
    carousel.goToNext()
  }
</script>

{#if browser}
  <Carousel
    bind:this={carousel}
  >
    <div>1</div>
    <div>2</div>
    <div>3</div>
  </Carousel>
{/if}

<button on:click={handleNextClick}>Next</button>

Vite support

  1. Extend optimizeDeps.include in vite.config.js
export default defineConfig({
  optimizeDeps: {
    include: ['lodash.get', 'lodash.isequal', 'lodash.clonedeep']
  }
})
  1. Import and use it:
<script>
  import Carousel from 'svelte-carousel'

  let carousel; // for calling methods of the carousel instance
  const handleNextClick = () => {
    carousel.goToNext()
  }
</script>

<Carousel
  bind:this={carousel}
>
  <div>1</div>
  <div>2</div>
  <div>3</div>
</Carousel>

<button on:click={handleNextClick}>Next</button>

Props

Prop Type Default Description
arrows boolean true Enables next/prev arrows
infinite boolean true Infinite looping
initialPageIndex number 0 Page to start on
duration number 500 Transition duration (ms)
autoplay boolean false Enables autoplay of pages
autoplayDuration number 3000 Autoplay change interval (ms)
autoplayDirection string 'next' Autoplay change direction (next or prev)
pauseOnFocus boolean false Pauses autoplay on focus (for touchable devices - tap the carousel to toggle the autoplay, for non-touchable devices - hover over the carousel to pause the autoplay)
autoplayProgressVisible boolean false Shows autoplay duration progress indicator
dots boolean true Current page indicator dots
timingFunction string 'ease-in-out' CSS animation timing function
swiping boolean true Enables swiping
particlesToShow number 1 Number of elements to show
particlesToScroll number 1 Number of elements to scroll

Events

pageChange

It is dispatched on page change

Payload field Type Description
event.detail number Current page index
<Carousel
  on:pageChange={
    event => console.log(`Current page index: ${event.detail}`)
  }
>
  <!-- -->
</Carousel>

Slots

prev and next

They are used for customizing prev and next buttons.

Slot props:

Prop Type Description
showPrevPage function Call it to switch to the previos page
showNextPage function Call it to switch to the next page
<Carousel
  let:showPrevPage
  let:showNextPage
>
  <div slot="prev">
    <!-- -->
  </div>
  <div slot="next">
    <!-- -->
  </div>
  <!-- -->
</Carousel>

dots

This slot is used for customizing how dots look like.

Slot props:

Prop Type Description
currentPageIndex number Represents current page index (start from 0)
pagesCount number Total pages amount
showPage function Takes index as page to be shown
<Carousel
  let:currentPageIndex
  let:pagesCount
  let:showPage
>
  <div slot="dots">
    <!-- -->
  </div>
  <!-- -->
</Carousel>

Default slot

This slot takes content for the carousel.

Slot props:

Prop Type Description
loaded number[] Contains indexes of pages to be loaded. Can be used for lazy loading
currentPageIndex number Represents current page index (start from 0)
<Carousel
  let:loaded
>
  <div>
    <!-- -->
  </div>
  <!-- -->
</Carousel>

Methods

goTo

Navigates to a page by index. (pageIndex, options) => Promise<void>.

Arguments:

Argument Type Default Description
pageIndex number Page number
options.animated boolean true Should it be animated or not
<script>
  // ...
  let carousel;
  function goToStartPage() {
    carousel.goTo(0, { animated: false })
  }
</script>

<Carousel
  bind:this={carousel}
>
  <!--  -->
</Carousel>
<button class="button" on:click={goToStartPage}>Go</button>

goToPrev

Navigates to the previous page. (options) => Promise<void>.

Arguments:

Argument Type Default Description
options.animated boolean true Should it be animated or not
<script>
  // ...
  let carousel;
  function goToPrevPage() {
    carousel.goToPrev({ animated: false })
  }
</script>

<Carousel
  bind:this={carousel}
>
  <!--  -->
</Carousel>
<button class="button" on:click={goToPrevPage}>Go</button>

goToNext

Navigates to the next page. (options) => Promise<void>.

Arguments:

Argument Type Default Description
options.animated boolean true Should it be animated or not
<script>
  // ...
  let carousel;
  function goToNextPage() {
    carousel.goToNext({ animated: false })
  }
</script>

<Carousel
  bind:this={carousel}
>
  <!--  -->
</Carousel>
<button class="button" on:click={goToNextPage}>Go</button>