MotionRail

Appearance

MotionRailBreakpoint ​

Responsive breakpoint configuration.

Type Definition ​

ts
type MotionRailBreakpoint = {
  width?: number;
  columns?: number;
  gap?: string;
};

Properties ​

width ​

Container width threshold in pixels.

  • Type: number
  • Optional: Yes (omit for base breakpoint)

Uses CSS Container Queries with min-width (mobile-first approach).

ts
const breakpoints = [
  { columns: 1, gap: "16px" }, // Base (no width)
  { width: 768, columns: 2, gap: "24px" }, // >= 768px
  { width: 1024, columns: 3, gap: "32px" }, // >= 1024px
];

Container Width, Not Viewport

The width value refers to the carousel container's width, not the viewport/screen width. MotionRail uses CSS Container Queries internally.

columns ​

Number of columns to display at this breakpoint.

  • Type: number
  • Optional: Yes
ts
const breakpoints = [
  { columns: 1 }, // 1 column
  { width: 768, columns: 2 }, // 2 columns at >= 768px
  { width: 1024, columns: 3 }, // 3 columns at >= 1024px
];

gap ​

Gap between items as a CSS value.

  • Type: string
  • Optional: Yes

Accepts any valid CSS gap value: px, rem, em, %, etc.

ts
const breakpoints = [
  { gap: "16px" },
  { width: 768, gap: "24px" },
  { width: 1024, gap: "2rem" },
  { width: 1280, gap: "5%" },
];

Usage Patterns ​

Basic Responsive Layout ​

ts
const carousel = new MotionRail(element, {
  breakpoints: [
    { columns: 1, gap: "16px" }, // Mobile
    { width: 768, columns: 2, gap: "24px" }, // Tablet
    { width: 1024, columns: 3, gap: "32px" }, // Desktop
  ],
});

Gap Only Changes ​

ts
const carousel = new MotionRail(element, {
  breakpoints: [
    { gap: "8px" }, // Small gap on mobile
    { width: 768, gap: "16px" }, // Medium gap on tablet
    { width: 1024, gap: "24px" }, // Large gap on desktop
  ],
});

Columns Only Changes ​

ts
const carousel = new MotionRail(element, {
  breakpoints: [
    { columns: 1 }, // 1 column
    { width: 640, columns: 2 }, // 2 columns
    { width: 1024, columns: 4 }, // 4 columns
  ],
});

Variable Columns (1 → 2 → 3 → 4) ​

ts
const carousel = new MotionRail(element, {
  breakpoints: [
    { columns: 1, gap: "16px" }, // Mobile: 1 column
    { width: 640, columns: 2, gap: "16px" }, // >= 640px: 2 columns
    { width: 1024, columns: 3, gap: "24px" }, // >= 1024px: 3 columns
    { width: 1280, columns: 4, gap: "32px" }, // >= 1280px: 4 columns
  ],
});

Mixed Units ​

ts
const carousel = new MotionRail(element, {
  breakpoints: [
    { columns: 1, gap: "1rem" },
    { width: 768, columns: 2, gap: "1.5rem" },
    { width: 1024, columns: 3, gap: "2rem" },
  ],
});

How Breakpoints Work ​

Mobile-First Approach ​

Breakpoints use min-width and are applied in order from smallest to largest:

ts
// This configuration:
[
  { columns: 1, gap: "16px" }, // Base
  { width: 768, columns: 2, gap: "24px" }, // >= 768px
  { width: 1024, columns: 3, gap: "32px" }, // >= 1024px
];

// Applies like this:
// Container width 0-767px:    1 column, 16px gap
// Container width 768-1023px: 2 columns, 24px gap
// Container width 1024px+:    3 columns, 32px gap

Partial Overrides ​

Each breakpoint only needs to specify the properties that change:

ts
const breakpoints = [
  { columns: 2, gap: "16px" }, // Base: 2 columns, 16px gap
  { width: 768, gap: "24px" }, // >= 768px: Still 2 columns, but 24px gap
  { width: 1024, columns: 4 }, // >= 1024px: 4 columns, still 24px gap
];

Container Queries ​

MotionRail uses CSS Container Queries, so breakpoints respond to the container's width, not the viewport:

html
<!-- Container is 600px wide, even on a 1920px screen -->
<div style="width: 600px">
  <div id="carousel">...</div>
</div>
ts
// This breakpoint won't activate because the container is 600px
{ width: 768, columns: 2 }

Next Steps ​