https://github.com/pascal-brand38/astro-splide
The Astro component for Splide dedicated to slides / carousel / photo swiper
https://github.com/pascal-brand38/astro-splide
astro astro-integration splide splidejs
Last synced: 11 months ago
JSON representation
The Astro component for Splide dedicated to slides / carousel / photo swiper
- Host: GitHub
- URL: https://github.com/pascal-brand38/astro-splide
- Owner: pascal-brand38
- License: mit
- Created: 2025-03-22T18:55:02.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-21T16:07:22.000Z (12 months ago)
- Last Synced: 2025-06-21T16:07:47.041Z (12 months ago)
- Topics: astro, astro-integration, splide, splidejs
- Language: TypeScript
- Homepage: https://pascal-brand38.github.io/astro-dev/packages/astro-splide/
- Size: 1.65 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Astro Splide
Astro Splide is the native Astro component for the
Splide,
dedicated to slides / carousel / photo swiper.
[Demo](https://pascal-brand38.github.io/astro-dev/packages/astro-splide)
# 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';
---
```
## 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](https://splidejs.com/guides/structure/) 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
...
Prev
Next
```
In the same way, you can add an autoplay toggle button and progress bar like so:
```jsx
...
Play
Pause
```
...or:
```jsx
Play
Pause
...
```
# 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
```
## 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](https://splidejs.com/guides/structure/#role).
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](https://splidejs.com/guides/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](https://github.com/pascal-brand38/astro-splide/blob/main/src/js/types/events.ts).
```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](https://splidejs.com/extensions/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,
},
}
---
...
...
...
import { initSplideExtension } from "astro-splide/js/splideExtensionUtils"
import { AutoScroll } from '@splidejs/splide-extension-auto-scroll'; // update with your extension
initSplideExtension({AutoScroll}) // update with your extension
```
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';
---
```
You can see working examples in [this page](https://pascal-brand38.github.io/astro-dev/packages/astro-splide).
This points to the
[example source files](https://github.com/pascal-brand38/astro-dev/tree/main/src/content/docs/packages/astro-splide)
# Support Splide
Please support the project if you like it!
- [Github Star astro-splide](https://github.com/pascal-brand38/astro-splide)
- [GitHub Sponsors @splidejs/splide](https://github.com/sponsors/NaotoshiFujita)
## License
Astro Splide and Splide are released under the MIT license.
© 2024 Pascal Brand
© 2021 Naotoshi Fujita