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>]

1. emblaRef: A function ref to be assigned to the ref attribute of your viewport element.
2. emblaApi: A Solid accessor (signal) that returns the Embla API instance once initialized.