Item 1
Item 2
Item 1
Item 2
Item 1
Item 2
Item 3
Item 4
Item 5
Visible items: {currentState.visibleItemIndexes.join(", ")}
Total items: {currentState.totalItems}
{item}
))}
Item 1
Item 2
{/* ...carousel item content... */}
))}
Item 1
Item 2
Item 3
Item 1
Item 2
Item 3
Item 4
Item 5
Visible items: {currentState.visibleItemIndexes.join(", ")}
Total items: {currentState.totalItems}
{item}
))}
Item 1
Item 2
{/* ...carousel item content... */}
))}
Item 1
Item 2
Item 3
Item 1
Item 2
Item 1
Item 2
Item 1
Item 2
Item 3
Item 4
Item 5
Visible items: {currentState().visibleItemIndexes.join(", ")}
Total items: {currentState().totalItems}
Item 1
Item 2
Item 3
{item}
}Item 1
Item 2
Item 1
Item 2
Item 3
Item 1
Item 2
Item 1
Item 2
Item 3
Item 4
Item 5
Visible items: {{ currentState.visibleItemIndexes.join(", ") }}
Total items: {{ currentState.totalItems }}
{{ item }}
Item 1
Item 2
{/* ...carousel item content... */}
{/each}
Item 1
Item 2
Item 3
Item 1
Item 2
Item 1
Item 2
Item 1
Item 2
Item 3
Item 4
Item 5
Visible items: {currentState.visibleItemIndexes.join(', ')}
Total items: {currentState.totalItems}
{item}
{/each}
Item 1
Item 2
{/* ...carousel item content... */}
))}
Item 1
Item 2
Item 3
Item 1
Item 2
Item 3
Item 4
Item 5
Visible items: {currentState.value.visibleItemIndexes.join(", ")}
Total items: {currentState.value.totalItems}
Item {item}
))}
Item 1
Item 2
Item 1
Item 2
Item 3
...
```
::: warning
Do not modify this property directly. It is managed internally by the carousel.
:::
---
### `scrollable`
The scrollable container element (the element with `data-motionrail-scrollable` attribute).
- **Type:** `HTMLElement`
- **Readonly:** Yes (enforced in TypeScript only)
```ts
const carousel = new MotionRail(document.getElementById("carousel"));
console.log(carousel.scrollable); // ...
// You can read scroll position
console.log(carousel.scrollable.scrollLeft);
```
::: warning
Do not modify this property directly. It is managed internally by the carousel.
:::
## Methods
### Playback Control
#### `play()`
Start autoplay scrolling.
```ts
play(): void
```
**Example:**
```ts
carousel.play();
```
::: tip
Autoplay must be enabled in options for this to work.
:::
---
#### `pause()`
Pause autoplay scrolling.
```ts
pause(): void
```
**Example:**
```ts
carousel.pause();
```
### Navigation
#### `next()`
Navigate to the next page. Automatically pauses autoplay if enabled.
```ts
next(): void
```
**Example:**
```ts
carousel.next();
```
---
#### `prev()`
Navigate to the previous page. Automatically pauses autoplay if enabled.
```ts
prev(): void
```
**Example:**
```ts
carousel.prev();
```
---
#### `scrollToIndex()`
Scroll to a specific item by its index (0-based). Automatically pauses autoplay if enabled.
```ts
scrollToIndex(index: number): void
```
**Parameters:**
- `index` - Zero-based index of the item to scroll to
**Example:**
```ts
carousel.scrollToIndex(2); // Scroll to the third item
```
### State & Information
#### `getState()`
Get the current carousel state.
```ts
getState(): MotionRailState
```
**Returns:** [MotionRailState](/docs/api/types/motionrail-state) object
**Example:**
```ts
const state = carousel.getState();
console.log(state.visibleItemIndexes); // [0, 1, 2]
console.log(state.totalItems); // 10
console.log(state.isFirstItemVisible); // true
console.log(state.isLastItemVisible); // false
```
---
#### `getOptions()`
Get the current carousel configuration options. Returns a copy to prevent external modifications.
```ts
getOptions(): MotionRailOptions
```
**Returns:** [MotionRailOptions](/docs/api/types/motionrail-options) object
**Example:**
```ts
const options = carousel.getOptions();
console.log(options.autoplay); // false
console.log(options.breakpoints); // [{ columns: 1, gap: '16px' }, ...]
```
### Content Management
#### `update()`
Refresh the carousel after dynamically adding or removing items from the DOM.
```ts
update(): void
```
This method:
- Recounts total items
- Recaches snap points
- Re-observes edge items with IntersectionObserver
- Reapplies breakpoints
- Triggers onChange callback with updated state
**Example:**
```ts
// Add items to the DOM
const grid = document.querySelector("[data-motionrail-grid]");
const newItem = document.createElement("div");
newItem.textContent = "New Item";
grid.appendChild(newItem);
// Update carousel to recognize new items
carousel.update();
```
::: tip Framework Users
Framework integrations (React, Solid, Vue, Svelte) automatically call `update()` when children change. You don't need to call it manually.
:::
### Lifecycle
#### `destroy()`
Clean up event listeners, observers, and timers. Call this when removing the carousel from the DOM.
```ts
destroy(): void
```
**Example:**
```ts
// Component unmount/cleanup
function cleanup() {
if (carousel) {
carousel.destroy();
carousel = null;
}
}
```
## Complete Example
```ts
import { MotionRail } from "motionrail";
import "motionrail/style.css";
const carousel = new MotionRail(document.getElementById("carousel"), {
autoplay: true,
breakpoints: [
{ columns: 1, gap: "16px" },
{ width: 768, columns: 2, gap: "16px" },
],
onChange: (state) => {
console.log("Visible items:", state.visibleItemIndexes);
},
});
// Playback controls
document.getElementById("play").addEventListener("click", () => {
carousel.play();
});
document.getElementById("pause").addEventListener("click", () => {
carousel.pause();
});
// Navigation
document.getElementById("prev").addEventListener("click", () => {
carousel.prev();
});
document.getElementById("next").addEventListener("click", () => {
carousel.next();
});
// Jump to specific item
document.querySelectorAll(".jump-button").forEach((btn, index) => {
btn.addEventListener("click", () => {
carousel.scrollToIndex(index);
});
});
// Get current state
const state = carousel.getState();
console.log("Current state:", state);
// Dynamic content
document.getElementById("add-item").addEventListener("click", () => {
const grid = document.querySelector("[data-motionrail-grid]");
const newItem = document.createElement("div");
newItem.textContent = "New Item";
grid.appendChild(newItem);
carousel.update();
});
// Cleanup on page unload
window.addEventListener("beforeunload", () => {
carousel.destroy();
});
```
## Next Steps
- [MotionRailOptions](/docs/api/types/motionrail-options) - Configuration options type
- [MotionRailState](/docs/api/types/motionrail-state) - State object type
- [Configuration](/docs/configuration) - All configuration options
- [Extensions](/docs/extensions/) - Extend functionality
---
# 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[];
containerName?: string;
};
```
## 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.
- **Type:** [MotionRailBreakpoint](/docs/api/types/motionrail-breakpoint)[]
- **Default:** `undefined`
```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
],
});
```
---
### `containerName`
Unique CSS container name for scoping container queries and styles to a specific carousel instance. This prevents style leakage and enables FOUC-free (Flash of Unstyled Content) rendering, especially with SSR. If not provided, a random name is generated automatically.
- **Type:** `string`
- **Default:** Randomly generated
```ts
const { containerName, containerQueries } = MotionRail.getBreakPoints({
breakpoints: [
{ columns: 1, gap: "16px" },
{ width: 768, columns: 2, gap: "24px" },
{ width: 1024, columns: 3, gap: "32px" },
],
totalItems: 8,
containerName: "my-carousel-container",
});
const carousel = new MotionRail(element, {
breakpoints: [
{ columns: 1, gap: "16px" },
{ width: 768, columns: 2, gap: "24px" },
{ width: 1024, columns: 3, gap: "32px" },
],
containerName: "my-carousel-container",
});
```
See [MotionRailBreakpoint](/docs/api/types/motionrail-breakpoint) and [Breakpoints Guide](/docs/breakpoints).
---
### `extensions`
Extension plugins to add functionality.
- **Type:** [MotionRailExtension](/docs/api/types/motionrail-extension)[]
- **Default:** `undefined`
```ts
import { Arrows } from "motionrail/extensions/arrows";
import { Dots } from "motionrail/extensions/dots";
const carousel = new MotionRail(element, {
extensions: [Arrows(), Dots()],
});
```
See [MotionRailExtension](/docs/api/types/motionrail-extension) and [Extensions](/docs/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
- [MotionRailState](/docs/api/types/motionrail-state)
- [MotionRailBreakpoint](/docs/api/types/motionrail-breakpoint)
- [MotionRailExtension](/docs/api/types/motionrail-extension)
- [Configuration Guide](/docs/configuration)
---
# 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
- [MotionRail Class](/docs/api/class/motionrail)
- [MotionRailOptions](/docs/api/types/motionrail-options)
- [onChange Callback](/docs/configuration#onchange)
---
# 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
];
```
::: tip 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
...