Preact Integration

MotionRail provides a first-class Preact component with full TypeScript support.

FOUC-Free Styling Example

import { MotionRail } from "motionrail/preact";
import { MotionRail as MotionRailClass } from "motionrail";
import "motionrail/style.css";

export default function Home() {
  // FOUC-safe container query setup for the first carousel
  const { containerName, containerQueries } = MotionRailClass.getBreakPoints({
    breakpoints: [
      { columns: 1, gap: "16px" },
      { width: 768, columns: 2, gap: "16px" },
      { width: 1024, columns: 3, gap: "20px" },
    ],
    totalItems: 8,
  });

  return (
    <section>
      {/* FOUC prevention: inject containerQueries in a <style> tag */}
      {containerName && containerQueries && (
        <style data-motionrail-style={containerName}>{containerQueries}</style>
      )}
      <MotionRail
        options={{
          breakpoints: [
            { columns: 1, gap: "16px" },
            { width: 768, columns: 2, gap: "16px" },
            { width: 1024, columns: 3, gap: "20px" },
          ],
          containerName,
        }}
      >
        {[1, 2, 3, 4, 5, 6, 7, 8].map((i) => (
          <div key={i}>{/* ...carousel item content... */}</div>
        ))}
      </MotionRail>
    </section>
  );
}

Basic Usage

import { MotionRail } from "motionrail/preact";
import "motionrail/style.css";

// Define options outside to prevent re-renders
const options = { breakpoints: [{ columns: 3, gap: "20px" }] };

function App() {
  return (
    <MotionRail options={options}>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </MotionRail>
  );
}

Props

options

• Type: MotionRailOptions
• Required: No

Configuration options for the carousel. See Configuration for all available options.

const options = {
  autoplay: true,
  delay: 3000,
  breakpoints: [
    { columns: 1, gap: "16px" },
    { width: 768, columns: 2, gap: "16px" },
  ],
};

<MotionRail options={options}>{/* items */}</MotionRail>;

Other Props

All other props are passed to the root div element:

const options = {};

<MotionRail
  options={options}
  className="my-carousel"
  style={{ maxWidth: "1200px" }}
  aria-label="Product carousel"
>
  {/* items */}
</MotionRail>;

WARNING

Unlike React, Preact does not expose refs to access the MotionRail instance. If you need programmatic control, consider using the vanilla JavaScript API directly.

Complete Example

import { useState } from "preact/hooks";
import { MotionRail } from "motionrail/preact";
import "motionrail/style.css";

function Carousel() {
  const [currentState, setCurrentState] = useState(null);

  const options = {
    autoplay: true,
    delay: 3000,
    breakpoints: [
      { columns: 1, gap: "16px" },
      { width: 768, columns: 2, gap: "16px" },
      { width: 1024, columns: 3, gap: "20px" },
    ],
    onChange: setCurrentState,
  };

  return (
    <div>
      <MotionRail options={options} className="my-carousel">
        <div>Item 1</div>
        <div>Item 2</div>
        <div>Item 3</div>
        <div>Item 4</div>
        <div>Item 5</div>
      </MotionRail>

      {currentState && (
        <div className="state-info">
          <p>Visible items: {currentState.visibleItemIndexes.join(", ")}</p>
          <p>Total items: {currentState.totalItems}</p>
        </div>
      )}
    </div>
  );
}

Dynamic Children

The Preact component automatically calls update() when children change:

import { useState } from "preact/hooks";
import { MotionRail } from "motionrail/preact";

// Define options outside to prevent re-renders
const options = { breakpoints: [{ columns: 3, gap: "20px" }] };

function DynamicCarousel() {
  const [items, setItems] = useState(["Item 1", "Item 2", "Item 3"]);

  const addItem = () => {
    setItems([...items, `Item ${items.length + 1}`]);
  };

  const removeItem = () => {
    setItems(items.slice(0, -1));
  };

  return (
    <>
      <MotionRail options={options}>
        {items.map((item, index) => (
          <div key={index}>{item}</div>
        ))}
      </MotionRail>

      <button onClick={addItem}>Add Item</button>
      <button onClick={removeItem}>Remove Item</button>
    </>
  );
}

TypeScript

Full TypeScript support is included:

import { MotionRail } from "motionrail/preact";
import type { MotionRailOptions, MotionRailState } from "motionrail";

function TypedCarousel() {
  const options: MotionRailOptions = {
    autoplay: true,
    breakpoints: [{ columns: 3, gap: "20px" }],
    onChange: (state: MotionRailState) => {
      console.log(state);
    },
  };

  return (
    <MotionRail options={options}>
      <div>Item 1</div>
      <div>Item 2</div>
    </MotionRail>
  );
}

Bundle Size

Preact integration: 0.82 kB (gzipped: 0.40 kB)

Next Steps

• Configuration - All configuration options
• API Methods - Programmatic control
• Extensions - Add more functionality