MotionRail

Appearance

MotionRailOptions ​

Configuration options for the carousel.

Type Definition ​

ts
type MotionRailOptions = {
  autoplay?: boolean;
  resumeDelay?: number;
  delay?: number;
  rtl?: boolean;
  onChange?: (state: MotionRailState) => void;
  breakpoints?: MotionRailBreakpoint[];
  extensions?: MotionRailExtension[];
}

Properties ​

autoplay ​

Enable automatic scrolling through items.

  • Type: boolean
  • Default: false
ts
const carousel = new MotionRail(element, {
  autoplay: true
});

resumeDelay ​

Milliseconds to wait before resuming autoplay after user interaction.

  • Type: number
  • Default: 3000
ts
const carousel = new MotionRail(element, {
  autoplay: true,
  resumeDelay: 5000  // Wait 5 seconds before resuming
});

delay ​

Milliseconds between autoplay scrolls.

  • Type: number
  • Default: 3000
ts
const carousel = new MotionRail(element, {
  autoplay: true,
  delay: 4000  // Scroll every 4 seconds
});

rtl ​

Enable right-to-left scrolling mode.

  • Type: boolean
  • Default: false
ts
const carousel = new MotionRail(element, {
  rtl: true
});

onChange ​

Callback function triggered when carousel state changes.

  • Type: (state: MotionRailState) => void
  • Default: undefined
ts
const carousel = new MotionRail(element, {
  onChange: (state) => {
    console.log('Visible items:', state.visibleItemIndexes);
    console.log('Total items:', state.totalItems);
    console.log('First visible:', state.isFirstItemVisible);
    console.log('Last visible:', state.isLastItemVisible);
  }
});

breakpoints ​

Responsive breakpoint configurations.

ts
const carousel = new MotionRail(element, {
  breakpoints: [
    { columns: 1, gap: '16px' },              // Base: 1 column
    { width: 768, columns: 2, gap: '24px' },  // >= 768px: 2 columns
    { width: 1024, columns: 3, gap: '32px' }  // >= 1024px: 3 columns
  ]
});

See MotionRailBreakpoint and Breakpoints Guide.

extensions ​

Extension plugins to add functionality.

ts
import { Arrows } from 'motionrail/extensions/arrows';
import { Dots } from 'motionrail/extensions/dots';

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

See MotionRailExtension and Extensions.

Complete Example ​

ts
import { MotionRail } from 'motionrail';
import { Arrows } from 'motionrail/extensions/arrows';
import { Dots } from 'motionrail/extensions/dots';
import 'motionrail/style.css';
import 'motionrail/extensions/arrows/style.css';
import 'motionrail/extensions/dots/style.css';

const carousel = new MotionRail(document.getElementById('carousel'), {
  autoplay: true,
  delay: 4000,
  resumeDelay: 5000,
  rtl: false,
  onChange: (state) => {
    console.log('State changed:', state);
  },
  breakpoints: [
    { columns: 1, gap: '16px' },
    { width: 768, columns: 2, gap: '24px' },
    { width: 1024, columns: 3, gap: '32px' }
  ],
  extensions: [
    Arrows(),
    Dots({ dotSize: 48 })
  ]
});

Next Steps ​