Solid JS
The Embla Carousel Solid package allows you to integrate Embla Carousel into your Solid JS applications using a reactive primitive. It provides a seamless way to connect Embla’s engine with Solid’s fine-grained reactivity.
Installation
To get started, install the embla-carousel-solid package along with the core library:
npm install embla-carousel-solid embla-carousel
Basic Usage
The primary way to use Embla in Solid is through the useEmblaCarousel primitive. This primitive returns a ref to be attached to the viewport element and a signal containing the emblaApi.
import useEmblaCarousel from 'embla-carousel-solid'
export function EmblaCarousel() {
const [emblaRef] = useEmblaCarousel()
return (
<div class="embla">
<div class="embla__viewport" ref={emblaRef}>
<div class="embla__container">
<div class="embla__slide">Slide 1</div>
<div class="embla__slide">Slide 2</div>
<div class="embla__slide">Slide 3</div>
</div>
</div>
</div>
)
}
Configuration
Options
To customize the carousel, pass an options object as the first argument. To maintain reactivity, options should be wrapped in a function (getter).
const [emblaRef] = useEmblaCarousel(() => ({
loop: true,
align: 'start'
}))
Plugins
Plugins are passed as the second argument, also wrapped in a function.
import Autoplay from 'embla-carousel-autoplay'
import useEmblaCarousel from 'embla-carousel-solid'
export function EmblaCarousel() {
const [emblaRef] = useEmblaCarousel(
() => ({ loop: true }),
() => [Autoplay()]
)
// ...
}
Accessing the API
The emblaApi is a signal that becomes defined once the carousel has initialized. You can use Solid's createEffect to interact with the API, such as listening to events or calling methods.
import { createEffect, on } from 'solid-js'
import useEmblaCarousel from 'embla-carousel-solid'
export function EmblaCarousel() {
const [emblaRef, emblaApi] = useEmblaCarousel()
createEffect(
on(emblaApi, (api) => {
if (!api) return
api.on('select', () => {
console.log(`Current snap index: ${api.selectedSnap()}`)
})
})
)
return (
<div class="embla" ref={emblaRef}>
{/* ... */}
</div>
)
}
Global Options
If you want to apply specific options to all carousels across your application, you can set globalOptions on the useEmblaCarousel primitive.
import useEmblaCarousel from 'embla-carousel-solid'
useEmblaCarousel.globalOptions = { loop: true }
TypeScript
embla-carousel-solid is written in TypeScript and provides full type safety. You can import types directly from the core library for use within your components.
import { EmblaOptionsType, EmblaCarouselType } from 'embla-carousel'
import useEmblaCarousel from 'embla-carousel-solid'
const options: EmblaOptionsType = { loop: false }
const [emblaRef, emblaApi] = useEmblaCarousel(() => options)
API Reference
useEmblaCarousel
| Argument | Type | Description |
| :--- | :--- | :--- |
| options | () => EmblaOptionsType | A function returning the configuration options. |
| plugins | () => EmblaPluginType[] | A function returning an array of plugins. |
Returns:
[emblaRef: (node: HTMLElement) => void, emblaApi: Accessor<EmblaCarouselType | undefined>]
- emblaRef: A function ref to be assigned to the
refattribute of your viewport element. - emblaApi: A Solid accessor (signal) that returns the Embla API instance once initialized.