MotionRailExtension

Extension plugin interface.

Type Definition

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

Properties

name

Unique identifier for the extension.

• Type: string
• Required: Yes

const customExtension: MotionRailExtension = {
  name: 'custom-logger'
};

---

onInit

Called once when the carousel is initialized.

• Type: (motionRail: MotionRail, state: MotionRailState) => void
• Optional: Yes

Parameters:

• motionRail - The MotionRail instance
• state - Current MotionRailState

const customExtension: MotionRailExtension = {
  name: 'init-tracker',
  onInit: (motionRail, state) => {
    console.log('Carousel initialized with', state.totalItems, 'items');
  }
};

---

onUpdate

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

• Type: (motionRail: MotionRail, state: MotionRailState) => void
• Optional: Yes

Parameters:

• motionRail - The MotionRail instance
• state - Updated MotionRailState

const customExtension: MotionRailExtension = {
  name: 'scroll-tracker',
  onUpdate: (motionRail, state) => {
    console.log('Visible items:', state.visibleItemIndexes);
  }
};

---

onDestroy

Called when the carousel is destroyed for cleanup.

• Type: (motionRail: MotionRail, state: MotionRailState) => void
• Optional: Yes

Parameters:

• motionRail - The MotionRail instance
• state - Final MotionRailState

const customExtension: MotionRailExtension = {
  name: 'cleanup-tracker',
  onDestroy: (motionRail, state) => {
    console.log('Carousel destroyed');
  }
};

Lifecycle Order

Extensions follow this lifecycle:

1. onInit - Carousel initialization (called once)
2. onUpdate - State changes (called multiple times)
3. onDestroy - Carousel cleanup (called once)

const lifecycleExtension: MotionRailExtension = {
  name: 'lifecycle-demo',
  onInit: (motionRail, state) => {
    console.log('1. Init');
  },
  onUpdate: (motionRail, state) => {
    console.log('2. Update (called on scroll, resize, etc.)');
  },
  onDestroy: (motionRail, state) => {
    console.log('3. Destroy');
  }
};

Usage

Adding Extensions

import { MotionRail } from 'motionrail';

const carousel = new MotionRail(element, {
  extensions: [
    customExtension1,
    customExtension2
  ]
});

Built-in Extensions

import { Arrows } from 'motionrail/extensions/arrows';
import { Dots } from 'motionrail/extensions/dots';
import { Thumbnails } from 'motionrail/extensions/thumbnails';
import { Logger } from 'motionrail/extensions/logger';

const carousel = new MotionRail(element, {
  extensions: [
    Arrows(),
    Dots({ dotSize: 48 }),
    Thumbnails(),
    Logger()
  ]
});

See Extensions Overview for built-in extensions.

Examples

Simple Logger

const logger: MotionRailExtension = {
  name: 'simple-logger',
  onInit: (motionRail, state) => {
    console.log('Initialized');
  },
  onUpdate: (motionRail, state) => {
    console.log('State updated:', state);
  },
  onDestroy: (motionRail, state) => {
    console.log('Destroyed');
  }
};

Counter Display

const counter: MotionRailExtension = {
  name: 'counter',
  onUpdate: (motionRail, state) => {
    const counterEl = document.querySelector('.counter');
    if (counterEl) {
      const current = state.visibleItemIndexes[0] + 1;
      counterEl.textContent = `${current} / ${state.totalItems}`;
    }
  }
};

Custom Controls

const customControls: MotionRailExtension = {
  name: 'custom-controls',
  onInit: (motionRail, state) => {
    const prevBtn = document.querySelector('.my-prev');
    const nextBtn = document.querySelector('.my-next');
    
    prevBtn?.addEventListener('click', () => motionRail.prev());
    nextBtn?.addEventListener('click', () => motionRail.next());
  },
  onUpdate: (motionRail, state) => {
    const prevBtn = document.querySelector('.my-prev') as HTMLButtonElement;
    const nextBtn = document.querySelector('.my-next') as HTMLButtonElement;
    
    if (prevBtn) prevBtn.disabled = state.isFirstItemVisible;
    if (nextBtn) nextBtn.disabled = state.isLastItemVisible;
  }
};

Progress Bar

const progressBar: MotionRailExtension = {
  name: 'progress-bar',
  onInit: (motionRail, state) => {
    const container = motionRail.getOptions();
    const progressEl = document.createElement('div');
    progressEl.className = 'progress-bar';
    progressEl.style.cssText = 'height: 4px; background: #ccc; position: relative;';
    
    const bar = document.createElement('div');
    bar.className = 'progress-bar-fill';
    bar.style.cssText = 'height: 100%; background: #007bff; width: 0; transition: width 0.3s;';
    
    progressEl.appendChild(bar);
    // Insert progress bar before carousel
  },
  onUpdate: (motionRail, state) => {
    const bar = document.querySelector('.progress-bar-fill') as HTMLElement;
    if (bar && state.totalItems > 0) {
      const progress = ((state.visibleItemIndexes[0] + 1) / state.totalItems) * 100;
      bar.style.width = `${progress}%`;
    }
  }
};

Keyboard Navigation

const keyboardNav: MotionRailExtension = {
  name: 'keyboard-navigation',
  onInit: (motionRail, state) => {
    const handleKeydown = (e: KeyboardEvent) => {
      if (e.key === 'ArrowLeft') motionRail.prev();
      if (e.key === 'ArrowRight') motionRail.next();
    };
    
    document.addEventListener('keydown', handleKeydown);
    
    // Store for cleanup
    (motionRail as any)._keyboardHandler = handleKeydown;
  },
  onDestroy: (motionRail, state) => {
    const handler = (motionRail as any)._keyboardHandler;
    if (handler) {
      document.removeEventListener('keydown', handler);
    }
  }
};

External State Sync

const stateSync: MotionRailExtension = {
  name: 'state-sync',
  onUpdate: (motionRail, state) => {
    // Sync to external state management (Redux, Vuex, etc.)
    window.dispatchEvent(new CustomEvent('carousel-state-change', {
      detail: state
    }));
  }
};

TypeScript Support

Full TypeScript support with type checking:

import { MotionRail } from 'motionrail';
import type { MotionRailExtension, MotionRailState } from 'motionrail';

const typedExtension: MotionRailExtension = {
  name: 'typed-extension',
  onInit: (motionRail: MotionRail, state: MotionRailState) => {
    // Full type checking and autocomplete
    console.log(state.totalItems);
    motionRail.play();
  }
};

Next Steps

• Creating Custom Extensions - Detailed guide
• Built-in Extensions - Arrows, Dots, Thumbnails, Logger
• MotionRail Class
• MotionRailState