@slidy/svelte

v3.4.4

Published

4 months ago

Simple, configurable & reusable carousel component built with SvelteJS

Downloads

853

0High
0Medium
0Low

valexr

carousel component svelte sveltejs svelte-plugin

@slidy/svelte

Simple, configurable & reusable carousel component built with SvelteJS based on @slidy/core.

Try the demo.

Getting started

The package is available via npm:

npm i @slidy/svelte

Playground is available in REPL.

Usage

The most simple way to get started is to use named import of <Slidy /> component:

<script>
	import { Slidy } from "@slidy/svelte";

	const slides = [
		{
			id: 1,
			width: 800,
			height: 1200,
			src: "static/img/some-image.webp",
		},
	];
</script>

<Slidy {slides} />

All props are optional. The only property to get started is slides - an array of objects with image related data.

Core Component

Core is a wrapper component for @slidy/core available via named import. It is best to use to build up the custom component for specific needs or when just the basic functionality is needed.

<script>
	import { Core } from "@slidy/svelte";
</script>

<Core>
	<!-- your carousel items passed via slot -->
</Core>

Core Component API

For TypeScript users there is the SlidyCoreOptions interface available via named import.

Slidy Component

<Slidy /> component uses <Core /> internally and provides more features expected from carousel.

Slidy Component API

The <Slidy /> component interface extends the <Core />. There are a list of additional options available:

By default component works with images. Image object should contain width and height attributes to prevent layout shifts and alt for accessibility.

Styling

Extending/Overriding classes

To extend default component styles use classNames property. Default classes are available via object, that can be extended or overridden:

<script>
	import { Slidy, classNames } from "@slidy/svelte";
</script>

<Slidy
	classNames={{
		root: `${classNames.root} custom-class`,
		...classNames
	}}
/>

The classNames consist of { target: className } pairs:

| Target | Default class | Description | | :-------- | :----------------: | :-----------| | arrow | slidy-arrow | Arrow controls. | | autoplay | slidy-autoplay | Autoplay control. | | counter | slidy-counter | Slide progress counter. | | img | slidy-img | Slide image node. | | nav | slidy-nav | Slide navigation panel. | | nav-item | slidy-nav-item | Navigtion panel item. | | overlay | slidy-overlay | Slides overlay node. | | progress | slidy-progress | Slide progress bar. | | progress-handle | slidy-progress-hadle | Slide progress bar control handle. | | root | slidy | Component's root node. | | slide | slidy-slide | Slide item node. | | slides | slidy-slides | Slides list node. | | thumbnail | slidy-thumbnail | Thumbnail item. | | thumbnail | slidy-thumbnails | Thumbnails bar. |

The classNames object is available via context using classNames key.

Custom Properties API

For easier style customization Slidy provides a set of predefined custom properties to inherit:

List of available public custom properties:

There are two options:

--style-props

Svelte supports passing down custom properties to component via --style-props:

<Slidy --slidy-slide-gap="1rem" />

Bear in mind that this way Svelte wraps the component in extra <div /> with display: contents.

Inherited custom properties

More optimal way is to use cascade. All supported custom properties starts with --slidy-. For example, to recolor navigation controls, let the component inherit a --slidy-nav-item-color custom property from any parent:

<div class="parent">
	<Slidy />
</div>

<style>
	.parent {
		--slidy-navigation-color: red;
	}
</style>

Or just pass a class with a set of custom properties:

<script>
	import { Slidy, classNames } from "@slidy/svelte";
</script>

<Slidy
	classNames={{
		root: `${classNames.root} .some-class`,
		...classNames
	}}
/>

<style>
	.some-class {
		--slidy-navigation-color: red;
		--slidy-nav-item-size: 1rem;
	}
</style>

Slots

`arrow`

Customizes the content of the default arrow controls.

`arrows`

Provides a slot for custom arrow buttons.

If the nodes are <button /> and the data-step attribute is present, the event listener is not needed. Just provide the values -1 and 1 for data-step on custom buttons.

Also, there are grid-area is present in the layout for this custom controls: prev-slide and next-slide respectively.

<Slidy>
	<svelte:fragment slot="arrows">
		<button data-step="-1"> Show the previous slide </button>
		<button data-step="1"> Show the next slide </button>
	</svelte:fragment>
</Slidy>

<style>
	button:first-of-type {
		grid-area: prev-slide;
	}

	button:last-of-type {
		grid-area: next-slide;
	}
</style>

`default`

Usually the default markup is not enough. The default slot solves this problem. To use custom slide markup slot expose each slides prop item as let:item directive.

<Slidy let:item>
	<figure>
		<img src={item.src} alt={item.figcaption} />
		<figcaption>
			{item.figcaption}
		</figcaption>
	</figure>
</Slidy>

`nav-item`

Provides a slot for custom pagination buttons. Slot receives optional index and active props for proper functionality.

Custom navigation item should be a <button /> and have data-index attribute to function. Otherwise, control the component externally.

<Slidy let:active let:index>
	<button slot="nav-item" data-index={index} {active} {index} />
</Slidy>

`overlay`

Slot to display content overlaid content. It covers the slides area and can be customized by overriding the .slidy-overlay. For example, it is used to display the counter.

<Slidy>
	<svelte:fragment slot="overlay">
		<button> Share </button>
	</svelte:fragment>
</Slidy>

`thumbnail`

Work in progress

Events

The component forwards custom events:

| Name | Description | Event detail | | :-------- | :------------------------------- | :-----------------------------------: | | destroy | Component is destroyed. | node | | index | The current slide index changes. | { index: number, position: number } | | keys | The key pressed on focus. | event.code | | mount | Component is mounted to the DOM. | { childs, options } | | move | Navigation occurs. | { index: number, position: number } | | resize | Component's dimentions changes. | { node, options } | | update | Component's props changes. | options |

i18n

To modify all texts used in the component use pass the dictionary as i18n prop. For the sake of accessibility, it is recommended translating defaults:

| Key | Default | Event detail | | :-------- | :------------------------------ | :-----------------------------------: | | carousel| "carousel" | aria-label of a root element. | | counter | "%s of %s" | aria-label of each slide as {slide number} of {slide length} | | first | "Go to the first slide" | aria-label of the first item at the navigation. | | last | "Go to the last slide" | aria-label of the last item at the navigation. | | next | "Go to the next slide" | aria-label of the arrow control. | | play | "Start autoplay" | aria-label of the autoplay control. | | prev | "Return back to previous slide" | aria-label of the arrow control. | | slide | "Slide" | aria-roledescription of each slide item. | | slideN | "Go to the slide %s" | aria-label of pagination of each slide item. | | stop | "Stop autoplay" | aria-label of the autoplay control. |

Recipes

External controls

It is possible to control the navigation of the Slidy instance from the parent component via binding.

There are two variables available to control the component externally: index and position. Declare the variables to hold the values and bind them to the instance for the carousel control.

<script>
	import { Slidy } from "svelte-slidy";

	let index = 0;
	let position = 0;
</script>

<button on:click={() => (index += 1)}> Next slide </button>

<button on:click={() => (position += 50)}> Move </button>

<Slidy bind:index bind:position />

Possible issues

Slides should not have absolute positioning, otherwise the core-package script won't get correct dimentions;
Using the background option usually is not recommended. In case you need to use it, specify the slide sizes with custom properties: width and height, or just aspect-ratio.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@slidy/svelte

Getting started

Usage

Core Component

Core Component API

Slidy Component

Slidy Component API

Styling

Extending/Overriding classes

Custom Properties API

--style-props

Inherited custom properties

Slots

arrow

arrows

default

nav-item

overlay

thumbnail

Events

i18n

Recipes

External controls

Possible issues

License

`arrow`

`arrows`

`default`

`nav-item`

`overlay`

`thumbnail`