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