Extensions

MotionRail supports a modular extension system that allows you to add functionality without bloating the core library.

Built-in Extensions

MotionRail comes with several pre-built extensions:

• Arrows - Previous/next navigation arrows
• Dots - Pagination dots indicator
• Thumbnails - Thumbnail navigation
• Logger - Debug logging for development

Installation

Extensions are included with MotionRail but must be imported separately:

import { MotionRail } from "motionrail";
import { Arrows } from "motionrail/extensions/arrows";
import { Dots } from "motionrail/extensions/dots";

// Don't forget to import extension styles
import "motionrail/style.css";
import "motionrail/extensions/arrows/style.css";
import "motionrail/extensions/dots/style.css";

Using Extensions

Add extensions through the extensions option:

const carousel = new MotionRail(element, {
  breakpoints: [
    { columns: 1, gap: "16px" },
    { width: 768, columns: 2, gap: "16px" },
  ],
  extensions: [Arrows({ loop: true }), Dots({ showIndex: true })],
});

Extension API

All extensions follow a consistent lifecycle API:

interface MotionRailExtension {
  name: string;
  onInit?: (motionRail: MotionRail, state: MotionRailState) => void;
  onUpdate?: (motionRail: MotionRail, state: MotionRailState) => void;
  onDestroy?: (motionRail: MotionRail, state: MotionRailState) => void;
}

See MotionRailExtension for complete type documentation.

Lifecycle Hooks

onInit(motionRail, state)

Called once when the carousel initializes. Use this to set up DOM elements, event listeners, or initial state.

Parameters:

• motionRail - The MotionRail instance
• state - Current MotionRailState

onUpdate(motionRail, state)

Called whenever the carousel state changes (scroll, resize, content update).

Parameters:

• motionRail - The MotionRail instance
• state - Updated MotionRailState

onDestroy(motionRail, state)

Called when the carousel is destroyed. Use this to clean up DOM elements, event listeners, and timers.

Parameters:

• motionRail - The MotionRail instance
• state - Final MotionRailState

State Object

All hooks receive the current state:

interface MotionRailState {
  totalItems: number; // Total number of items
  visibleItemIndexes: number[]; // Currently visible item indexes
  isFirstItemVisible: boolean; // First item is visible
  isLastItemVisible: boolean; // Last item is visible
}

See MotionRailState for complete type documentation.

Multiple Extensions

You can use multiple extensions together:

import { Arrows } from "motionrail/extensions/arrows";
import { Dots } from "motionrail/extensions/dots";
import { Thumbnails } from "motionrail/extensions/thumbnails";

const carousel = new MotionRail(element, {
  extensions: [
    Arrows({ loop: false }),
    Dots({ showIndex: true }),
    Thumbnails({ thumbnailWidth: 80 }),
  ],
});

Next Steps

• Arrows Extension - Navigation arrows
• Dots Extension - Pagination indicators
• Thumbnails Extension - Thumbnail navigation
• Logger Extension - Debug logging
• Creating Custom Extensions - Build your own