svelte-carousel/README.md

svelte-carousel

The awesome carousel component for Svelte 3

Demo

• vadimkorr.github.io/svelte-carousel
• REPL

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

2. 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: []
    }
  }
}

3. 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']
  }
})

2. 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>