svelte-carousel/README.md

# @resultium/svelte-carousel

This is a fork of [svelte-carousel](https://github.com/vadimkorr/svelte-carousel) project originally made bt [vadimkorr](https://github.com/vadimkorr) made due to lack of maintainment of the original package

This package is not published to any public registries due to being intended to be used exclusively in Resultium projects, however you are free to fork or use this codebase as per Apache-2.0 license 

## Usage

1. Install as development dependancy
2. Import and use

```svelte
<script>
  import Carousel from '@resultium/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>
```

## 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                    |

```svelte
<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    |

```svelte
<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              |

```svelte
<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)                         |

```svelte
<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          |

```svelte
<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  |

```svelte
<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 |

```svelte
<script>
  // ...
  let carousel;
  function goToNextPage() {
    carousel.goToNext({ animated: false })
  }
</script>

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