MotionRail

Appearance

MotionRailState ​

Current state of the carousel.

Type Definition ​

ts
type MotionRailState = {
  totalItems: number;
  visibleItemIndexes: number[];
  isFirstItemVisible: boolean;
  isLastItemVisible: boolean;
};

Properties ​

totalItems ​

Total number of items in the carousel.

  • Type: number
ts
const state = carousel.getState();
console.log(state.totalItems); // 10

visibleItemIndexes ​

Array of currently visible item indexes (0-based).

  • Type: number[]
ts
const state = carousel.getState();
console.log(state.visibleItemIndexes); // [0, 1, 2]

This array updates as the user scrolls and items enter/exit the viewport.

isFirstItemVisible ​

Whether the first item is currently visible.

  • Type: boolean
ts
const state = carousel.getState();
console.log(state.isFirstItemVisible); // true

// Use for disabling "previous" button
const prevButton = document.querySelector(".prev-button");
prevButton.disabled = state.isFirstItemVisible;

isLastItemVisible ​

Whether the last item is currently visible.

  • Type: boolean
ts
const state = carousel.getState();
console.log(state.isLastItemVisible); // false

// Use for disabling "next" button
const nextButton = document.querySelector(".next-button");
nextButton.disabled = state.isLastItemVisible;

Usage ​

Getting Current State ​

Use the getState() method to retrieve the current state:

ts
const state = carousel.getState();
console.log(state);
// {
//   totalItems: 10,
//   visibleItemIndexes: [0, 1, 2],
//   isFirstItemVisible: true,
//   isLastItemVisible: false
// }

Listening to State Changes ​

Use the onChange option to receive state updates:

ts
const carousel = new MotionRail(element, {
  onChange: (state) => {
    console.log("Total:", state.totalItems);
    console.log("Visible:", state.visibleItemIndexes);
    console.log("At start:", state.isFirstItemVisible);
    console.log("At end:", state.isLastItemVisible);
  },
});

Common Patterns ​

Disable Navigation at Boundaries ​

ts
const prevButton = document.querySelector(".prev");
const nextButton = document.querySelector(".next");

const carousel = new MotionRail(element, {
  onChange: (state) => {
    prevButton.disabled = state.isFirstItemVisible;
    nextButton.disabled = state.isLastItemVisible;
  },
});

Update Pagination Counter ​

ts
const counter = document.querySelector(".counter");

const carousel = new MotionRail(element, {
  onChange: (state) => {
    const currentPage = state.visibleItemIndexes[0] + 1;
    counter.textContent = `${currentPage} / ${state.totalItems}`;
  },
});

Custom Dot Indicators ​

ts
const dotsContainer = document.querySelector(".dots");

const carousel = new MotionRail(element, {
  onChange: (state) => {
    // Update active dot based on first visible item
    const firstVisibleIndex = state.visibleItemIndexes[0];
    document.querySelectorAll(".dot").forEach((dot, index) => {
      dot.classList.toggle("active", index === firstVisibleIndex);
    });
  },
});

Conditional Auto-Pause ​

ts
const carousel = new MotionRail(element, {
  autoplay: true,
  onChange: (state) => {
    // Pause when reaching the last item
    if (state.isLastItemVisible) {
      carousel.pause();
    }
  },
});

Next Steps ​