Breakpoints

Breakpoints allow you to configure how many columns and what gap size to use at different container widths, creating a fully responsive carousel.

Configuration

interface MotionRailBreakpoint {
  width?: number;   // Maximum viewport width (optional)
  columns?: number; // Number of visible columns (optional)
  gap?: string;     // Gap between items (optional, CSS value)
}

See MotionRailBreakpoint for complete type documentation.

How Breakpoints Work

Breakpoints are applied mobile-first. Start with your default configuration (no width property), then add breakpoints with increasing width values.

ELEMENT WIDTH, NOT SCREEN WIDTH

The width values in breakpoints refer to the carousel container's width, not the viewport/screen width. MotionRail uses CSS Container Queries internally, making carousels responsive to their parent container rather than the screen size.

WARNING

The examples below assume the carousel container is full-width. If your carousel is constrained within a narrower container, adjust the breakpoint values accordingly.

Basic Example

// the following is an example for full-width carousel
const carousel = new MotionRail(element, {
  breakpoints: [
    { columns: 1, gap: '16px' },                    // Default (mobile)
    { width: 768, columns: 2, gap: '16px' },        // Tablets
    { width: 1024, columns: 3, gap: '20px' }        // Desktop
  ]
});

How it applies:

• 0-767px: 1 column, 16px gap
• 768-1023px: 2 columns, 16px gap
• 1024px+: 3 columns, 20px gap

Common Patterns

Variable Columns (1 → 2 → 3 → 4)

breakpoints: [
  { columns: 1, gap: '12px' },                    // < 480px
  { width: 480, columns: 2, gap: '16px' },        // 480px - 767px
  { width: 768, columns: 3, gap: '20px' },        // 768px - 1023px
  { width: 1024, columns: 4, gap: '24px' }        // >= 1024px
]

Fixed Layout (No Responsiveness)

breakpoints: [
  { columns: 2, gap: '20px' }  // Always 2 columns at any width
]

Mobile-First Progressive Enhancement

breakpoints: [
  { columns: 1, gap: '8px' },                     // Small phones
  { width: 375, columns: 1, gap: '12px' },        // Standard phones
  { width: 640, columns: 2, gap: '16px' },        // Phablets/small tablets
  { width: 768, columns: 2, gap: '20px' },        // Tablets
  { width: 1024, columns: 3, gap: '24px' },       // Small desktops
  { width: 1280, columns: 4, gap: '28px' },       // Standard desktops
  { width: 1536, columns: 5, gap: '32px' }        // Large screens
]

Columns Only (Consistent Gap)

breakpoints: [
  { columns: 1 },
  { width: 768, columns: 2 },
  { width: 1024, columns: 3 }
]
// Gap defaults to "0px" for all breakpoints

Gap Only (Single Column)

breakpoints: [
  { columns: 1, gap: '12px' },
  { width: 768, gap: '20px' },
  { width: 1024, gap: '28px' }
]
// Always 1 column, but gap increases on larger screens

Default Behavior

If you omit the breakpoints option entirely, MotionRail uses this default:

breakpoints: [
  { columns: 1, gap: "0px" }
]

Important Notes

Width Ordering

WARNING

Breakpoints must be ordered from smallest to largest width. The first breakpoint should have no width property.

❌ Wrong:

breakpoints: [
  { width: 1024, columns: 3, gap: '20px' },  // This won't work as intended
  { width: 768, columns: 2, gap: '16px' },
  { columns: 1, gap: '16px' }
]

✅ Correct:

breakpoints: [
  { columns: 1, gap: '16px' },               // Default (no width)
  { width: 768, columns: 2, gap: '16px' },
  { width: 1024, columns: 3, gap: '20px' }
]

Container Queries

MotionRail uses CSS Container Queries internally, which means breakpoints respond to the carousel container's width, not the viewport width. This allows carousels to be responsive within their parent container.

Gap Values

The gap property accepts any valid CSS value:

breakpoints: [
  { columns: 2, gap: '16px' },                // Pixels
  { width: 768, columns: 2, gap: '1rem' },    // Rem units
  { width: 1024, columns: 2, gap: '2%' },     // Percentage
  { width: 1280, columns: 2, gap: '1.5em' }   // Em units
]

Dynamic Updates

Changes to breakpoints require recreating the carousel instance:

let carousel = new MotionRail(element, {
  breakpoints: [{ columns: 2, gap: '16px' }]
});

// To change breakpoints:
carousel.destroy();
carousel = new MotionRail(element, {
  breakpoints: [{ columns: 3, gap: '20px' }]
});

Examples

E-commerce Product Grid

breakpoints: [
  { columns: 2, gap: '12px' },        // Mobile: 2 products
  { width: 640, columns: 3, gap: '16px' },   // Small tablets: 3 products
  { width: 1024, columns: 4, gap: '20px' },  // Desktop: 4 products
  { width: 1280, columns: 5, gap: '24px' }   // Large screens: 5 products
]

Image Gallery

breakpoints: [
  { columns: 1, gap: '0px' },         // Mobile: full-width images
  { width: 768, columns: 2, gap: '8px' },    // Tablets: 2 images
  { width: 1024, columns: 3, gap: '12px' }   // Desktop: 3 images
]

Content Carousel

breakpoints: [
  { columns: 1, gap: '20px' },        // Mobile: one card at a time
  { width: 1024, columns: 2, gap: '32px' }   // Desktop: two cards
]

Next Steps

• Configuration - All configuration options
• API Methods - Programmatic control
• Examples - More real-world examples