SSR

The SSR plugin enables server-side rendering support for Embla Carousel by generating stable CSS transforms before the browser dimensions are available, preventing layout shifts on hydration.

Installation

Start by installing the npm package and save it to your dependencies:

<script src="https://unpkg.com/embla-carousel-ssr/embla-carousel-ssr.umd.js"></script>

npm install embla-carousel-ssr --save

pnpm add embla-carousel-ssr

yarn add embla-carousel-ssr

Options

Below follows an exhaustive list of all Ssr options and their default values.

breakpoints

{   slideSizes: [50, 50, 50],  breakpoints: {    '(min-width: 768px)': { slideSizes: [70, 70, 70] }  }}

An object with options that will be applied for a given breakpoint by overriding the options at the root level. Use this when your slide sizes change at CSS breakpoints.

slideSizes

{ slideSizes: [50, 50, 50] }

An array of slide sizes expressed as percentages of the carousel viewport. Each number corresponds to a slide and must exactly match the CSS width (or height for vertical carousels) applied to that slide.

Methods

Below follows an exhaustive list of all Ssr methods with their respective parameters and return values.

getStyles

emblaApi.plugins().ssr?.getStyles('#carousel', '.embla__slide')

Generates a CSS string containing the transform styles needed to position the carousel container and any looping slides at the correct starting position on the server.

The containerSelector must be a unique CSS selector that targets only the container element of the carousel this plugin instance belongs to. This prevents SSR styles from affecting other carousels on the same page.

The optional slidesSelector parameter defaults to > *, selecting all direct children of the container. Provide a more specific selector when your slide elements are not direct children or when you need to scope styles further.

Inject the returned string into a <style> tag in your server-rendered HTML before the client-side carousel initialises:

const styles = emblaApi.plugins().ssr?.getStyles('#my-carousel', '.embla__slide')// => "#my-carousel { transform: translate3d(-50%,0px,0px); }"