Virtual scroll

Lista virtualizada — 10 mil linhas, ~25 nós DOM.

Navegadores: Chrome 123+Firefox 121+Safari 17.5+
Nível: 2
Tamanho compactado: 4.16 kB
Limite de layout forçado: 0 ms
Limite do axe: 0
Compatível com SSR: Sim
Contrato publicado: Ambiente de teste

Experimentar

React

CSS

Tailwind

/* 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`

Prop	Tipo	Padrão	Descrição
`items`*	`T[]`	—	A lista completa de itens, cada um com id estável; apenas as linhas no intervalo atual são renderizadas.
`renderRow`*	`(item: T, index: number) => ReactNode`	—	Renderiza o conteúdo de uma linha a partir do item e do índice absoluto.
`height`	`number`	—	Altura explícita em pixels. Omita e passe style={{ blockSize: '100%' }} para preencher uma altura definida no pai; o padrão é 600px quando nenhum dos dois é fornecido.
`rowHeight`	`number`	`64`	Tamanho fixo em pixels de cada linha no eixo de rolagem (altura na vertical, largura na horizontal), usado para calcular o tamanho da rolagem e as linhas visíveis.
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Eixo de rolagem. Listas horizontais rolam no eixo inline, dimensionam a janela pela largura medida da área visível, espelham corretamente em layouts da direita para a esquerda e refletem o valor em `data-orientation`.
`overscan`	`number`	`5`	Número de linhas extras renderizadas acima e abaixo do intervalo visível para que a rolagem rápida não revele espaços vazios.
`estimateRowHeight`	`(index: number) => number`	—	Estimativa de altura por índice que muda a lista para layout dinâmico, no qual as linhas renderizadas são medidas e a estimativa é corrigida.
`role`	`"list" \| "grid"`	`"list"`	Papel ARIA aplicado ao contêiner de rolagem.
`anchor`	`"start" \| "end"`	`"start"`	Extremidade da lista à qual a posição de rolagem fica fixada quando itens são adicionados ou removidos.
`followAppend`	`boolean \| "smooth"`	`false`	Rola para os itens recém-adicionados quando a lista já está no fim, opcionalmente com rolagem suave.
`scrollRef`	`Ref<VirtualScrollHandle>`	—	Recebe a referência imperativa que expõe scrollToIndex, scrollToOffset e scrollToEnd.
`onRangeChange`	`(range: VirtualScrollRangeChange) => void`	—	Chamado com os intervalos de índices visíveis e pré-renderizados sempre que a janela renderizada se move.
`onScrollStateChange`	`(state: VirtualScrollScrollState) => void`	—	Chamado quando a rolagem começa e quando termina.
`isScrollingResetDelay`	`number`	`150`	Milissegundos sem movimento para considerar a rolagem concluída em navegadores sem o evento scrollend.
`className`	`string`	—	Classe aplicada ao contêiner de rolagem.
`testId`	`string`	—	Valor do atributo data-testid do contêiner de rolagem.

Teclado

Tecla	Ação
`Scroll`	Roda do mouse, trackpad ou barra de rolagem movem a janela
`Tab`	Mova o foco entre controles das linhas (checkbox, acionador de menu)
`Arrow keys`	Percorra os itens de um menu suspenso aberto
`Escape`	Feche um menu suspenso aberto

Acessibilidade

Um espaçador de altura total mantém a barra de rolagem nativa precisa enquanto apenas um conjunto fixo de espaços de linha, mais a margem de pré-renderização, fica montado; chaves estáveis desses espaços reciclam os nós DOM. As linhas expõem role="listitem" com aria-posinset e aria-setsize em uma área de rolagem role="list". A sincronização da rolagem é passiva, e saltos grandes, como pela barra de rolagem, Home/End ou Cmd+Arrow, atualizam o intervalo de forma síncrona.

Pontos de integração de estilos

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

Framework

Estilo

Tema

Idioma

Virtual scroll

Experimentar

Virtual scroll

Horizontal

API

`VirtualScroll`

Teclado

Acessibilidade

Pontos de integração de estilos