Virtual scroll

Список с виртуализацией — 10 тыс. строк, около 25 узлов DOM.

Браузеры: Chrome 123+Firefox 121+Safari 17.5+
Уровень: 2
Сжатый размер: 4.16 kB
Лимит принудительной компоновки: 0 ms
Лимит axe: 0
Совместим с SSR: Да
Публичный контракт: Тестовый стенд

Песочница

React

CSS

Tailwind

import { VirtualScroll } from "@gunkin/uiify";

const items = Array.from({ length: 10000 }, (_, index) => ({
  id: String(index),
  label: "Row " + (index + 1),
}));

export default function Example() {
  return (
    <>
      <VirtualScroll className="" height={400} items={items} renderRow={(item) => <div>{item.label}</div>} />
      {/* rowHeight is the item size along the scroll axis — here, each card's width. */}
      <VirtualScroll
        className=""
        height={120}
        items={items}
        orientation="horizontal"
        rowHeight={144}
        renderRow={(item) => <div>{item.label}</div>}
      />
    </>
  );
}

/* Generic skin for custom core surfaces used by the demo and consumers. */

@layer components {
  [data-uiify-surface] {
    display: grid;
    gap: var(--space-md);
    inline-size: max-content;
    max-inline-size: min(28rem, calc(100vw - 2 * var(--space-lg)));
    padding: var(--space-lg);
    border: var(--border-width) solid var(--border);
    border-radius: var(--radius-xl);
    corner-shape: squircle;
    background-color: var(--card);
    color: var(--card-foreground);
    box-shadow: var(--shadow-popover);
  }

  [data-uiify-surface][popover]:not(:popover-open) {
    display: none;
  }

  @media (prefers-reduced-motion: no-preference) {
    [data-uiify-surface][popover] {
      transition: var(--transition-presence);
    }

    [data-uiify-surface][popover]:not(:popover-open) {
      opacity: 0;
      scale: var(--presence-scale);
    }

    @starting-style {
      [data-uiify-surface][popover]:popover-open {
        opacity: 0;
        scale: var(--presence-scale);
      }
    }
  }
}

import { VirtualScroll } from "@gunkin/uiify";

const items = Array.from({ length: 10000 }, (_, index) => ({
  id: String(index),
  label: "Row " + (index + 1),
}));

export default function Example() {
  return (
    <>
      <VirtualScroll
        className="
          grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl
          [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden
          motion-safe:[&[popover]]:[transition:var(--transition-presence)]
          motion-safe:[&[popover]:not(:popover-open)]:opacity-0
          motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)]
          motion-safe:starting:[&[popover]:popover-open]:opacity-0
          motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]
        "
        height={400}
        items={items}
        renderRow={(item) => <div>{item.label}</div>}
      />
      {/* rowHeight is the item size along the scroll axis — here, each card's width. */}
      <VirtualScroll
        className="
          grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl
          [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden
          motion-safe:[&[popover]]:[transition:var(--transition-presence)]
          motion-safe:[&[popover]:not(:popover-open)]:opacity-0
          motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)]
          motion-safe:starting:[&[popover]:popover-open]:opacity-0
          motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]
        "
        height={120}
        items={items}
        orientation="horizontal"
        rowHeight={144}
        renderRow={(item) => <div>{item.label}</div>}
      />
    </>
  );
}

/* app.css */

@layer reset, ui, app, tokens, base, demo, components, utilities, theme;

@import "@gunkin/uiify/styles/reset";

@import "@gunkin/uiify/components/behavior.css";

@import "@gunkin/uiify/styles/tokens";

@import "@gunkin/uiify/styles/tailwind";

@import "tailwindcss/utilities.css";

@theme { --spacing: 0.25rem; --font-weight-normal: 400; --font-weight-medium: 500; --font-weight-semibold: 600; --font-weight-bold: 700; }

@source inline('grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden motion-safe:[&[popover]]:[transition:var(--transition-presence)] motion-safe:[&[popover]:not(:popover-open)]:opacity-0 motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)] motion-safe:starting:[&[popover]:popover-open]:opacity-0 motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]');

@layer base { :root { --uiify-control-text: var(--text-sm); } @media (pointer: coarse) { :root { --uiify-control-text: var(--text-base); } } }

/* Authored animation and registered properties used by the Tailwind skin.
 * Visual rules belong in utility recipes; only at-rule definitions live here. */
@layer components {
  @keyframes uiify-presence-in {
    from {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@layer components {
  @keyframes uiify-presence-out {
    to {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@property --uiify-spinner-tail {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@property --uiify-spinner-length {
  syntax: "<angle>";
  inherits: false;
  initial-value: 36deg;
}

@layer components {
  @keyframes uiify-spinner-rotate {
    to {
      transform: rotate(360deg);
    }
  }
}

@layer components {
  @keyframes uiify-spinner-orbit {
    0% {
      --uiify-spinner-tail: 0deg;
      --uiify-spinner-length: 36deg;
    }

    50% {
      --uiify-spinner-tail: 90deg;
      --uiify-spinner-length: 324deg;
    }

    100% {
      --uiify-spinner-tail: 360deg;
      --uiify-spinner-length: 36deg;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-pulse {
    50% {
      opacity: 0.45;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-shimmer {
    to {
      background-position: -200% 0;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-reveal {
    from {
      opacity: 0;
    }
    to {
      opacity: 1;
    }
  }
}

@property --candle-body-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-body-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-slot {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 100%;
}

@property --candle-wick-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-wick-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-x {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@property --line-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-prev-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-count {
  syntax: "<integer>";
  inherits: false;
  initial-value: 1;
}

@property --line-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@layer components {
  @keyframes uiify-otp-input-caret-blink {
    50% {
      opacity: 0;
    }
  }
}

API

`VirtualScroll`

Свойство	Тип	По умолчанию	Описание
`items`*	`T[]`	—	Полный список элементов со стабильными идентификаторами; отображаются только строки текущего диапазона.
`renderRow`*	`(item: T, index: number) => ReactNode`	—	Отображает содержимое строки по её элементу и абсолютному индексу.
`height`	`number`	—	Явная высота в пикселях. Не задавайте её и передайте style={{ blockSize: '100%' }}, чтобы заполнить родителя с определённой высотой; если не задано ни то ни другое, используется 600px.
`rowHeight`	`number`	`64`	Фиксированный размер каждой строки в пикселях по оси прокрутки (высота по вертикали, ширина по горизонтали), используемый для расчёта размера прокрутки и видимых строк.
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Ось прокрутки. Горизонтальные списки прокручиваются по строчной оси, определяют размер окна по измеренной ширине области просмотра, корректно зеркалируются при письме справа налево и отражают значение в `data-orientation`.
`overscan`	`number`	`5`	Число дополнительных строк над и под видимым диапазоном, чтобы при быстрой прокрутке не появлялись пустоты.
`estimateRowHeight`	`(index: number) => number`	—	Оценка высоты по индексу, которая включает динамическую компоновку: отображённые строки измеряются, а оценка уточняется.
`role`	`"list" \| "grid"`	`"list"`	Роль ARIA контейнера прокрутки.
`anchor`	`"start" \| "end"`	`"start"`	Конец списка, к которому привязывается положение прокрутки при добавлении или удалении элементов.
`followAppend`	`boolean \| "smooth"`	`false`	Прокручивает к новым добавленным элементам, если список уже находится в конце; возможна плавная прокрутка.
`scrollRef`	`Ref<VirtualScrollHandle>`	—	Получает объект императивного управления с методами scrollToIndex, scrollToOffset и scrollToEnd.
`onRangeChange`	`(range: VirtualScrollRangeChange) => void`	—	Вызывается с диапазонами видимых и запасных индексов при каждом перемещении отображаемого окна.
`onScrollStateChange`	`(state: VirtualScrollScrollState) => void`	—	Вызывается при начале и завершении прокрутки.
`isScrollingResetDelay`	`number`	`150`	Пауза в миллисекундах, после которой прокрутка считается завершённой в браузерах без события scrollend.
`className`	`string`	—	Класс контейнера прокрутки.
`testId`	`string`	—	Значение атрибута data-testid контейнера прокрутки.

Клавиатура

Клавиша	Действие
`Scroll`	Перемещать окно списка колёсиком, трекпадом или полосой прокрутки
`Tab`	Перемещать фокус между элементами управления строки (флажком, триггером меню)
`Arrow keys`	Перемещаться по пунктам открытого выпадающего меню
`Escape`	Закрыть открытое выпадающее меню

Доступность

Распорка полной высоты сохраняет точность нативной полосы прокрутки, пока смонтирован лишь фиксированный пул ячеек строк с запасом; стабильные ключи ячеек позволяют переиспользовать узлы DOM. Строки имеют role="listitem" с aria-posinset и aria-setsize внутри области прокрутки с role="list". Синхронизация прокрутки пассивна, а большие переходы — полосой прокрутки, Home/End или Cmd+Arrow — обновляют диапазон синхронно.

Привязка стилей

data-uiify-virtual-scrolldata-part="spacer"data-part="row"

Фреймворк

Стиль

Тема

Язык

Virtual scroll

Песочница

Virtual scroll

Horizontal

API

`VirtualScroll`

Клавиатура

Доступность

Привязка стилей