Astro Splide

Astro Splide is the native Astro component for the
Splide,
dedicated to slides / carousel / photo swiper.

Installation

Get the latest version from NPM:
``



$ npm install astro-splide @splidejs/splide





Usage



Simple Example



Here is the astro code of a loop carousel, of 3 pictures, with 1 second interval.

jsx

---

import "@splidejs/splide/css"

import { Splide, SplideSlide } from 'astro-splide';

---

  class='not-content'

  options={ {  // check for options at https://splidejs.com/guides/options/

    type: 'loop',         // type of the carousel

    autoplay: true,       // activate autoplay

    interval: 1000,       // autoplay interval in milliseconds

    pauseOnHover: false,  // do not pause autoplay on mouseover

  } }

>







Components



Import Splide and SplideSlide components in frontmatter:

jsx

import { Splide, SplideSlide } from 'astro-splide';





...and render them like this:

jsx





If you have the visible heading for the carousel,

use

`aria-labelledby` instead of `aria-label`

.

See this page for more details.





CSS

Select a CSS file you want to use in frontmatter, and import it:

jsx

// Default theme

import '@splidejs/splide/css';



// or other themes

import '@splidejs/splide/css/skyblue';

import '@splidejs/splide/css/sea-green';



// or only core styles

import '@splidejs/splide/css/core';





Custom Structure

Although

`` renders a track element by default, you can handle them respectively with the hasTrack prop and the ``

 component. In a nutshell, following 2 components render the same HTML:

jsx

---

import { Splide, SplideTrack, SplideSlide } from 'astro-splide';

---



  ...







  

    ...





Separating

`` from ``

 allows you to place arrows, pagination or other controls anywhere outside the track in the similar way of vanilla Splide. For example, Splide renders arrows before a track by default, but you are able to specify the location with a placeholder:

jsx

...





...or with custom arrows:

jsx



  

    ...





In the same way, you can add an autoplay toggle button and progress bar like so:

jsx



  

    ...





...or:

jsx

...





Props

 accepts HTMLAttributes that will be assigned to a carousel root element, except for DOMAttributes. For instance, class and 'aria-label' are acceptable:

jsx





Additionally, it takes a few more props.



options

jsx

options: Options





Splide options as an object:

jsx

  options={ {

    rewind: true,

    width : 800,

    gap   : '1rem',

  } }

>

tag

jsx

tag: 'div' | 'section' | 'header' | 'footer' | 'nav' = 'div'





Allows you to specify the tag name used for the root element. Although the default value is div for backward compatibility, 'section' is recommended.



If you are using header, footer, or nav, you have to provide the most appropriate landmark role together. Otherwise, your accessibility tree will be invalid.

jsx





hasTrack

jsx

hasTrack: boolean = true





Determines whether to render a track or not.





Events

You can listen to all Splide events

through the Splide component. The name of the

callback function is generated by the original name with adding an "on" prefix,

converting the format to the camelcase and removing colons. For example,

"arrows:mounted" becomes "onArrowsMounted". The event list is available in

this file.

jsx

 { console.log( prev, next ) } }>





Note that the handler always takes the splide instance as the first argument, and original arguments after it.



Extensions



Using an extension requires some more code from the developer:

* Use

`SplideExtension` instead of `Splide`



* define the script part as follows. Note that it contains part related to the extension.

Modify it accordingly.



Typical code would be, here being the @splidejs/splide-extension-auto-scroll extension:

jsx

---

import "@splidejs/splide/css"

import { SplideExtension, SplideSlide } from 'astro-splide';

const options = {

  ...,   // regular options of splide

  autoScroll: {   // specific options of the used extension

    speed: 1,

  },

}

---



  ...

  ...

  ...





Note that it is the user responsability to install the splide extension



Limitations: a single extension can be used in a rendered page





Example

Here is a small example:

jsx

---

import "@splidejs/splide/css"

import { Splide, SplideSlide } from 'astro-splide';

---

  options={ {

    rewind: true,

    gap   : '1rem',

  } }

  aria-label="My Favorite Images"

>

``

You can see working examples in this page.
This points to the
example source files

Support Splide

Please support the project if you like it!
- Github Star astro-splide
- GitHub Sponsors @splidejs/splide

astro-splide

Astro Splide

Installation

Usage

Simple Example

Components

CSS

Custom Structure

Props

options

tag

hasTrack

Events

Extensions

Example

Support Splide

License