Creating Custom Extensions

Learn how to build your own MotionRail extensions.

Extension API

Extensions are objects that implement lifecycle hooks to interact with the carousel.

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.

State Object

The MotionRailState object passed to onInit, onUpdate, and onDestroy:

interface MotionRailState {
  totalItems: number; // Total number of items in carousel
  visibleItemIndexes: number[]; // Array of currently visible item indexes
  isFirstItemVisible: boolean; // Whether the first item is visible
  isLastItemVisible: boolean; // Whether the last item is visible
}

Lifecycle Hooks

Extensions can interact with the carousel through the MotionRail instance methods like prev(), next(), scrollToIndex(), and more.

onInit(motionRail, state)

Called once when the carousel is initialized.

Parameters:

• motionRail: MotionRail instance with API methods
• state: Initial MotionRailState

Use for:

• Creating DOM elements
• Setting up event listeners
• Initial configuration

onInit(motionRail, state) {
  console.log('Carousel initialized with', state.totalItems, 'items');
  // Create UI elements
  // Attach event listeners
}

onUpdate(motionRail, state)

Called whenever the carousel state changes (navigation, resize, etc).

Parameters:

• motionRail: MotionRail instance with API methods
• state: Updated MotionRailState

Use for:

• Updating UI based on state
• Responding to navigation
• Syncing external elements

onUpdate(motionRail, state) {
  console.log('Visible items:', state.visibleItemIndexes);
  // Update UI elements
  // Sync with other components
}

onDestroy(motionRail, state)

Called when the carousel is destroyed.

Parameters:

• motionRail: MotionRail instance
• state: Final MotionRailState

Use for:

• Cleanup event listeners
• Remove DOM elements
• Release resources

onDestroy(motionRail, state) {
  // Remove event listeners
  // Clean up DOM
  // Release resources
}

Simple Example

A counter that tracks visible items:

function Counter() {
  let counterElement;

  return {
    name: "counter",
    onInit(motionRail, state) {
      counterElement = document.createElement("div");
      counterElement.textContent = `Showing ${state.visibleItemIndexes.length} of ${state.totalItems}`;
      motionRail.container.appendChild(counterElement);
    },

    onUpdate(motionRail, state) {
      counterElement.textContent = `Showing ${state.visibleItemIndexes.length} of ${state.totalItems}`;
    },

    onDestroy() {
      counterElement?.remove();
    },
  };
}

// Usage
new MotionRail(element, {
  extensions: [Counter()],
});

Navigation Controls Example

A custom navigation extension:

function CustomControls() {
  let prevBtn, nextBtn;

  return {
    name: "custom-controls",
    onInit(motionRail, state) {
      // Create buttons
      const container = document.createElement("div");
      container.className = "custom-controls";

      prevBtn = document.createElement("button");
      prevBtn.textContent = "Previous";
      prevBtn.onclick = () => motionRail.prev(); // See MotionRail.prev()

      nextBtn = document.createElement("button");
      nextBtn.textContent = "Next";
      nextBtn.onclick = () => motionRail.next(); // See MotionRail.next()

      container.append(prevBtn, nextBtn);
      motionRail.container.appendChild(container);
    },

    onUpdate(motionRail, state) {
      // Disable prev when at start
      prevBtn.disabled = state.isFirstItemVisible;

      // Disable next when at end
      nextBtn.disabled = state.isLastItemVisible;
    },

    onDestroy() {
      prevBtn?.remove();
      nextBtn?.remove();
    },
  };
}

Progress Bar Example

A progress indicator showing first/last item visibility:

function ProgressBar() {
  let progressElement;

  return {
    name: "progress-bar",
    onInit(motionRail, state) {
      progressElement = document.createElement("div");
      progressElement.className = "carousel-progress";

      const bar = document.createElement("div");
      bar.className = "carousel-progress-bar";
      progressElement.appendChild(bar);

      motionRail.container.appendChild(progressElement);
    },

    onUpdate(motionRail, state) {
      const bar = progressElement.querySelector(".carousel-progress-bar");
      // Calculate progress based on scroll position
      const scrollPercentage =
        (motionRail.container.querySelector(".motionrail-container")
          .scrollLeft /
          (motionRail.container.querySelector(".motionrail-container")
            .scrollWidth -
            motionRail.container.querySelector(".motionrail-container")
              .clientWidth)) *
        100;
      bar.style.width = `${scrollPercentage}%`;
    },

    onDestroy() {
      progressElement?.remove();
    },
  };
}

CSS:

.carousel-progress {
  width: 100%;
  height: 4px;
  background: #e0e0e0;
  margin-top: 16px;
}

.carousel-progress-bar {
  height: 100%;
  background: #007bff;
  transition: width 0.3s ease;
}

Keyboard Navigation Example

Add keyboard controls to the carousel:

function KeyboardControls() {
  let handleKeydown;

  return {
    name: "keyboard-controls",
    onInit(motionRail, state) {
      handleKeydown = (e) => {
        if (e.key === "ArrowLeft") {
          motionRail.prev();
        } else if (e.key === "ArrowRight") {
          motionRail.next();
        }
      };

      document.addEventListener("keydown", handleKeydown);
    },

    onDestroy() {
      if (handleKeydown) {
        document.removeEventListener("keydown", handleKeydown);
      }
    },
  };
}

External Sync Example

Sync carousel with external UI elements:

function ExternalSync(config) {
  const { thumbnailContainer } = config;

  return {
    name: "external-sync",
    onInit(motionRail, state) {
      // Create thumbnail buttons for each item
      for (let i = 0; i < state.totalItems; i++) {
        const btn = document.createElement("button");
        btn.textContent = i + 1;
        btn.onclick = () => motionRail.scrollToIndex(i); // See MotionRail.scrollToIndex()
        thumbnailContainer.appendChild(btn);
      }
    },

    onUpdate(motionRail, state) {
      // Update active thumbnails based on visible items
      const buttons = thumbnailContainer.querySelectorAll("button");
      buttons.forEach((btn, i) => {
        btn.classList.toggle("active", state.visibleItemIndexes.includes(i));
      });
    },

    onDestroy() {
      thumbnailContainer.innerHTML = "";
    },
  };
}

// Usage
const thumbnailContainer = document.getElementById("thumbnails");

new MotionRail(element, {
  extensions: [ExternalSync({ thumbnailContainer })],
});

TypeScript Support

Full type definitions:

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

function MyExtension(): MotionRailExtension {
  let element: HTMLElement | null = null;

  return {
    name: "my-extension",
    onInit(motionRail: MotionRail, state: MotionRailState) {
      element = document.createElement("div");
      element.textContent = `Total items: ${state.totalItems}`;
      motionRail.container.appendChild(element);
    },

    onUpdate(motionRail: MotionRail, state: MotionRailState) {
      if (element) {
        element.textContent = `Visible: ${state.visibleItemIndexes.join(", ")}`;
      }
    },

    onDestroy() {
      element?.remove();
    },
  };
}

Best Practices

Cleanup Resources

Always clean up in onDestroy:

onDestroy(motionRail, state) {
  // Remove event listeners
  document.removeEventListener('keydown', handleKeydown);

  // Remove DOM elements
  element?.remove();

  // Clear references
  element = null;
}

Handle Missing Container

Check if elements exist before manipulating:

onUpdate(motionRail, state) {
  if (!element) return;
  element.textContent = `${state.visibleItemIndexes.length} visible`;
}

Use Configuration

Make extensions configurable:

function MyExtension(config = {}) {
  const { enabled = true, className = "default" } = config;

  return {
    name: "my-extension",
    onInit(motionRail, state) {
      if (!enabled) return;
      // Use config...
    },
  };
}

Prevent Memory Leaks

Store references properly:

function MyExtension() {
  let listeners = [];

  return {
    name: "my-extension",
    onInit(motionRail, state) {
      const handler = () => {
        /* ... */
      };
      listeners.push(handler);
      document.addEventListener("click", handler);
    },

    onDestroy() {
      listeners.forEach((handler) => {
        document.removeEventListener("click", handler);
      });
      listeners = [];
    },
  };
}

Next Steps

• Extensions Overview - Understanding the extension system
• Arrows Extension - Example extension source
• Dots Extension - Another example
• API Reference - Complete API documentation