# IndexedSnapScroller
## Summary
`IndexedSnapScroller` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) built on `SnapScroller` for virtualized, index-windowed paging. It maintains a sliding logical index sequence and can shift the window as the user reaches scroll boundaries.
## Imports
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
type IndexedSnapScrollerApiRef,
type IndexedSnapScrollerContentProps,
type IndexedSnapScrollerProps,
} from '@vega-ui/react';
```
## Exported Types
- `IndexedSnapScrollerProps`
- `IndexedSnapScrollerContentProps`
- `IndexedSnapScrollerApiRef`
## Minimal Composition
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
useIndexedSnapScrollerContext,
} from '@vega-ui/react';
const today = new Date();
const monthFormat = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
function MonthPage() {
const { index } = useIndexedSnapScrollerContext();
const month = new Date(today.getFullYear(), today.getMonth() + index, 1);
return (
{monthFormat.format(month)}
);
}
export default function MinimalComposition() {
return (
);
}
```
## Required Parts
- `IndexedSnapScroller`: root indexed paging system
- `IndexedSnapScrollerContent`: page content bound to the current virtual index
## Optional Parts
- `apiRef` for imperative index-window control
## Composition Order
1. `IndexedSnapScroller`
2. one `IndexedSnapScrollerContent` child template
## Variants
- Controlled logical `index`
- Uncontrolled windowed paging with `defaultIndex`
- Adjustable `size`, `shift`, `start`, and `startDir`
## Edge Cases
- Controlled `index` and virtual window resets should stay synchronized.
- `preserveScroll` changes how index-window shifts feel.
- The children are re-rendered for each virtual index, so keyed state inside the page content must be intentional.
## Common Mistakes
- Assuming child order stays static even though the virtual window shifts.
- Forgetting that one content template is rendered multiple times with different context indexes.
- Mixing external controlled index logic with ad hoc internal offset assumptions.
## Examples
### Basic
#### Basic: infinite week strip
One `WeekPage` template is rendered for every index in the window and reads its own index from `useIndexedSnapScrollerContext`; index 0 is the current week. The date math lives in the page component, the scroller only supplies the index.
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
} from '@vega-ui/react';
import type { CSSProperties } from 'react';
const today = new Date();
const daysSinceMonday = (today.getDay() + 6) % 7;
const weekdayFormat = new Intl.DateTimeFormat('en-US', { weekday: 'short' });
const weekFormat = new Intl.DateTimeFormat('en-US', { month: 'long', day: 'numeric' });
function WeekPage() {
const { index } = useIndexedSnapScrollerContext();
const days = Array.from({ length: 7 }, (_, day) => (
new Date(today.getFullYear(), today.getMonth(), today.getDate() - daysSinceMonday + index * 7 + day)
));
return (
{days.map((day) => {
const isToday = day.toDateString() === today.toDateString();
return (
{weekdayFormat.format(day)}
{day.getDate()}
);
})}
);
}
export default function WeekStrip() {
return (
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: month header with external controls
`index` lives in the parent and `onScrollSnapChange` writes the settled index back. The arrows call `apiRef.next()` and `prev()` for a smooth step; **+1 year** and **This month** set `index` directly, which rebuilds the window around a target outside it and jumps there without animation.
```tsx
import {
Button,
Icon,
IconButton,
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
type IndexedSnapScrollerApiRef,
} from '@vega-ui/react';
import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import { useRef, useState } from 'react';
const today = new Date();
const monthFormat = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
function countWorkingDays(year: number, month: number) {
const daysInMonth = new Date(year, month + 1, 0).getDate();
let count = 0;
for (let day = 1; day <= daysInMonth; day++) {
const weekday = new Date(year, month, day).getDay();
if (weekday !== 0 && weekday !== 6) count++;
}
return count;
}
function MonthPage() {
const { index } = useIndexedSnapScrollerContext();
const month = new Date(today.getFullYear(), today.getMonth() + index, 1);
const daysInMonth = new Date(month.getFullYear(), month.getMonth() + 1, 0).getDate();
return (
{monthFormat.format(month)}
{daysInMonth} days, {countWorkingDays(month.getFullYear(), month.getMonth())} working days
);
}
export default function ControlledVirtualIndex() {
const api = useRef(null);
const [index, setIndex] = useState(0);
return (
api.current?.prev()}>
api.current?.next()}>
setIndex(next)}
style={{ gap: 'var(--spacing-6)' }}
>
index = {index}
);
}
```
### Form/Integration
#### Form/Integration: delivery day in a form
Only the pages of the current window exist in the DOM, so the selected day cannot live in a page: it is kept in form state and submitted through a hidden input read with `FormData`. Submitting without a day shows a `HelperText` linked to the group with `aria-describedby`; past days and Sundays are disabled buttons, and reset clears the value and returns to the current week with `setIndexTo(0)`.
```tsx
import {
Button,
HelperText,
Icon,
IconButton,
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
type IndexedSnapScrollerApiRef,
} from '@vega-ui/react';
import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import { useRef, useState, type FormEvent } from 'react';
const today = new Date();
const todayStart = new Date(today.getFullYear(), today.getMonth(), today.getDate());
const daysSinceMonday = (today.getDay() + 6) % 7;
const weekdayFormat = new Intl.DateTimeFormat('en-US', { weekday: 'short' });
const fullDateFormat = new Intl.DateTimeFormat('en-US', { weekday: 'long', month: 'long', day: 'numeric' });
function toIsoDate(date: Date) {
const month = String(date.getMonth() + 1).padStart(2, '0');
const day = String(date.getDate()).padStart(2, '0');
return `${date.getFullYear()}-${month}-${day}`;
}
interface WeekPageProps {
selected: string
onSelect(value: string): void
}
function WeekPage({ selected, onSelect }: WeekPageProps) {
const { index } = useIndexedSnapScrollerContext();
const days = Array.from({ length: 7 }, (_, day) => (
new Date(today.getFullYear(), today.getMonth(), today.getDate() - daysSinceMonday + index * 7 + day)
));
return (
{days.map((day) => {
const value = toIsoDate(day);
const isSelected = value === selected;
const isUnavailable = day < todayStart || day.getDay() === 0;
return (
{weekdayFormat.format(day)}
);
})}
);
}
export default function WeekStripForm() {
const api = useRef(null);
const [selected, setSelected] = useState('');
const [error, setError] = useState('');
const [result, setResult] = useState('');
const select = (value: string) => {
setSelected(value);
setError('');
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
const deliveryDate = data.get('deliveryDate');
if (!deliveryDate) {
setError('Choose a delivery day. Sundays are not available.');
return;
}
setResult(`Delivery booked for ${deliveryDate}.`);
};
const onReset = () => {
setSelected('');
setError('');
setResult('');
api.current?.setIndexTo(0);
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: month picker in a popover
Pages are years, each with twelve month buttons. The popover renders its content only while open, so `defaultIndex` reopens the picker on the year of the selected month; choosing a month closes the popover and updates the trigger label.
```tsx
import {
Button,
IndexedSnapScroller,
IndexedSnapScrollerContent,
Popover,
PopoverContent,
PopoverTrigger,
Text,
useIndexedSnapScrollerContext,
} from '@vega-ui/react';
import { useState } from 'react';
const currentYear = new Date().getFullYear();
const monthNames = Array.from({ length: 12 }, (_, month) => (
new Intl.DateTimeFormat('en-US', { month: 'short' }).format(new Date(2000, month, 1))
));
interface Selection {
year: number
month: number
}
interface YearPageProps {
selected: Selection
onSelect(value: Selection): void
}
function YearPage({ selected, onSelect }: YearPageProps) {
const { index } = useIndexedSnapScrollerContext();
const year = currentYear + index;
return (
{year}
);
}
export default function MonthPickerInPopover() {
const [open, setOpen] = useState(false);
const [selected, setSelected] = useState({ year: currentYear, month: new Date().getMonth() });
const select = (value: Selection) => {
setSelected(value);
setOpen(false);
};
return (
);
}
```
### Edge
#### Edge: bounded range
The window is infinite, so bounds are your job: indexes before the first statement and after the current month render placeholder pages, and when the scroll settles on one of them `onScrollSnapChange` scrolls back to the nearest real statement. The scroll back is scheduled with `requestAnimationFrame` because the scroller re-centers its window right after the callback.
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
type IndexedSnapScrollerApiRef,
} from '@vega-ui/react';
import { useRef, useState, type CSSProperties } from 'react';
const today = new Date();
const accountOpened = new Date(2025, 0, 1);
const firstIndex = (accountOpened.getFullYear() - today.getFullYear()) * 12 + accountOpened.getMonth() - today.getMonth();
const lastIndex = 0;
const monthFormat = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
const pageStyle: CSSProperties = {
display: 'grid',
gap: 'var(--spacing-2)',
width: '100%',
padding: 'var(--spacing-10)',
boxSizing: 'border-box',
borderRadius: 'var(--radius-4)',
background: 'var(--fills-secondary)',
};
function StatementPage() {
const { index } = useIndexedSnapScrollerContext();
const month = new Date(today.getFullYear(), today.getMonth() + index, 1);
if (index < firstIndex) {
return (
Statements start in {monthFormat.format(accountOpened)}.
);
}
if (index > lastIndex) {
return (
The next statement is issued on the 1st.
);
}
return (
{monthFormat.format(month)}Statement #{index - firstIndex + 1}, PDF, 84 KB
);
}
export default function BoundedStatements() {
const api = useRef(null);
const [current, setCurrent] = useState(lastIndex);
const onSettle = (index: number) => {
if (index < firstIndex) {
requestAnimationFrame(() => api.current?.scrollToElementByKey(firstIndex));
return;
}
if (index > lastIndex) {
requestAnimationFrame(() => api.current?.scrollToElementByKey(lastIndex));
return;
}
setCurrent(index);
};
return (