# @xxfogs/svelte-carousel

This is a fork of [svelte-carousel](https://github.com/vadimkorr/svelte-carousel) project made due to it's lack of maintainment.

## Installation

```bash
yarn add -D @xxfogs/svelte-carousel
```

```bash
pnpm i -D @xxfogs/svelte-carousel
```

```bash
yarn i -D @xxfogs/svelte-carousel
```

## Usage

1. Install as development dependancy
2. Import and use

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