Pular para o conteúdo
Estrutura

VirtualList

/componentes/virtual-list.mdmarkdown cru, para quem lê com agent em vez de olho

Quatro mil itens

Conteúdo carregado

Texto que quebra em duas linhas

Conteúdo carregado

Altura cravada, sem medir

Conteúdo carregado

Com respiro entre os itens

Conteúdo carregado

Ir até um item que não está na tela

Conteúdo carregado

Carregando

Carregando…

Erro

Vazio

Nenhum evento por aqui

Quando o sistema registrar o primeiro evento, ele aparece nesta lista.

Conteúdo carregado
Importar
import { VirtualList } from '@rivocode/ui'

Quando usar

Lista longa que desenha só o que cabe na moldura.

O virtualizador já estava pago: o DataTable usa a mesma engrenagem desde que o painel de log entrou. O que faltava era a lista que não é tabela (o feed, o histórico de eventos, o seletor de dois mil clientes), e que até aqui ou montava dez mil <li> no DOM ou empurrava a pessoa para a paginação no servidor.

<VirtualList
  items={events}            // 4 mil itens
  itemKey={(event) => event.id}
  maxHeight={360}
  label="Log de eventos do sistema"
  renderItem={(event) => (
    <Item className="px-3">
      <ItemContent>
        <ItemTitle>{event.message}</ItemTitle>
        <ItemDescription>{event.at}</ItemDescription>
      </ItemContent>
    </Item>
  )}
/>

renderItem desenha um item; a peça cuida de quantos existem, de quais estão na tela e de quanto espaço os ausentes ocupam.

A partir de quantos itens

Abaixo de duzentos, não use. Uma lista curta virtualizada é complexidade paga sem retorno: entram uma altura obrigatória, um palpite de altura por item e um contêiner que rola por dentro, e o que se ganha são alguns milissegundos que ninguém sente. Duzentas linhas comuns montam em menos de um quadro.

Entre duzentos e uns dois mil, é escolha: se cada item for pesado (imagem, gráfico, um menu por linha), virtualizar já paga; se for texto, não.

Acima de dois mil, use. É onde a montagem inicial passa a travar o clique que abriu a tela, e é o ponto em que a ScrollArea com tudo no DOM começa a custar memória de verdade no celular.

A altura do item, que é a decisão da peça

Virtualizar é prometer, antes de desenhar, quanto espaço o que não foi desenhado vai ocupar. Toda a peça sai daí.

  • itemHeight (padrão 44, o mesmo do rowHeight do DataTable) é o palpite. É ele que dá comprimento à barra de rolagem antes de o item existir. Aceita número ou função por índice, para a lista que alterna item simples e item duplo.
  • measure (ligado de saída) faz cada item desenhado devolver a altura real, e a rolagem se corrigir. É o que segura texto que quebra em duas linhas a 390px: com o palpite sozinho, o item de duas linhas invade o de baixo e a barra promete um fim que não chega.

Com measure ligado, itemHeight só precisa estar perto: quem ainda não foi desenhado continua valendo o palpite, e o que já passou pela tela vale a medida. Por isso a barra de rolagem de uma lista de alturas variadas se ajusta enquanto se rola, e isso é honesto: a alternativa seria medir quatro mil itens na montagem, que é exatamente o custo que a peça existe para não pagar.

Desligue measure quando a altura for cravada por CSS. Aí itemHeight é a lei, a peça aplica essa altura em cada item, e você economiza um observador de tamanho por item visível. É o caso do log de largura fixa com uma linha por evento.

itemKey não é só chave de React: é por ela que a altura medida segue o item quando a lista reordena ou filtra. Índice serve e quebra na primeira reordenação: o item que era o terceiro herda a altura de quem estava ali.

Rolagem dentro da própria moldura

maxHeight é obrigatória quando a lista rola sozinha, e é a diferença para a irmã do DataTable, onde ela é opcional: sem altura não há o que caber, e uma lista virtualizada sem moldura desenha um item só. A moldura é a mesma da tabela (borda, canto e superfície iguais), ela rola por dentro em vez de empurrar a página, e é decisão escrita da casa desde a tabela.

gap põe respiro entre um item e o próximo sem que ele conte como altura de item. Margem dentro do renderItem não serve: a medida de um item é a caixa dele, e margem fica de fora. O resultado é uma lista que encolhe um pouco a cada item.

Rolagem de um ancestral, ou da página

Quando quem rola é a página inteira, ou um painel que já rola por fora, uma segunda barra de rolagem dentro dele é o defeito. getScrollElement diz quem rola: () => window para a página, ou o elemento do painel.

<VirtualList
  getScrollElement={() => window}
  items={events}
  itemKey={(event) => event.id}
  renderItem={(event) => <p>{event.message}</p>}
  label="Log de envio"
/>

Nesse modo a lista perde a moldura, a altura máxima e a parada de Tab própria (quem tem a barra de rolagem é o ancestral), cresce com o conteúdo e desenha só o que está à vista daquele rolamento. A distância entre o topo dele e o da lista é medida sozinha, de novo quando ele ou um filho direto dele muda de tamanho, e é descontada no scrollToIndex e no scrollToOffset. Passe uma função estável: ela não deveria mudar a cada desenho.

Contagem para o leitor de tela

Uma lista virtualizada mente por construção: com vinte itens no DOM e quatro mil na mão, o leitor de tela anuncia "item 3 de 20". O DataTable resolveu isso com aria-rowcount na tabela e aria-rowindex em cada linha; aqui vale o par equivalente de lista: aria-setsize com o total e aria-posinset com a posição real em cada item. Quem ouve ouve "3 de 4000", que é o que existe.

A peça sai como role="list" com role="listitem" dentro, e label é o nome dessa lista. Sem ele, ela é anunciada como uma lista sem nome no meio da tela. E numa tela que tem três, isso não distingue nenhuma.

Com paginação, a lista que chegou não é a lista que existe: com 50 de 4000 carregados, o leitor ouviria "3 de 50". totalCount é o total do servidor, e vira o aria-setsize de cada linha e a contagem do nome da lista. Sem ele, a peça conta o que chegou.

Lista agrupada intercala cabeçalho (o dia, a letra) entre as linhas, e o cabeçalho não é item: isHeader diz quais são. Eles rolam com a lista, mas saem como role="presentation", sem aria-setsize nem aria-posinset, e ficam fora da contagem e da posição das linhas. Passe uma função estável: a posição de cada linha se recalcula quando ela muda.

<VirtualList
  items={rows}               // cabeçalhos de dia e notas, intercalados
  totalCount={query.data?.pages[0]?.total}
  isHeader={isDayHeader}
  /* … */
/>

Carregando não há lista nenhuma: o esqueleto sai marcado com aria-hidden e a região não se anuncia como lista de quatro itens que não existem.

Ir até um item que não está na tela

Item que não foi desenhado não tem elemento, então scrollIntoView não alcança. ref recebe um VirtualListHandle, que tem scrollToIndex(index, { align, behavior }): start, center, end ou auto. É como se vai ao fim de um log ou se pula para o resultado de uma busca. scrollToOffset(pixels) anda uma distância medida do topo da lista, para restaurar a posição de quem voltou à página, e scrollToTop() volta ao começo. Com getScrollElement, quem anda é o ancestral.

const list = useRef<VirtualListHandle>(null)

<Button onClick={() => list.current?.scrollToIndex(events.length - 1, { align: 'end' })}>
  Último
</Button>
<VirtualList ref={list} items={events} /* … */ />

Os quatro estados

Os mesmos do DataTable, na mesma ordem e com os mesmos nomes de prop: erro vence carregando, e vazio só vale depois que a consulta voltou. isLoading e items === undefined são a mesma coisa; skeletonItems diz quantos itens falsos aparecem, e cada um ocupa a altura de itemHeight, para a moldura não pular quando os dados chegam. errorTitle, errorMessage, onRetry e labels.retry são o conjunto do erro, e empty é o estado vazio com descrição obrigatória. empty.illustration leva o desenho do vazio de página (EmptyList, NoResults, de @rivocode/ui/illustrations, ou o Bacalhau em produto da RivoCode) e vence o icon, que fica para a lista pequena, como no QueryBoundary.

Erro com linhas na mão não troca a lista. Sem items, isError é o aviso no lugar da lista. Com items, é a página seguinte de um useInfiniteQuery que falhou, e trocar as 50 linhas que já estavam na tela pelo aviso é perder o que a pessoa estava lendo: a lista fica, e o erro entra como a última linha, dentro da moldura, com o botão do onRetry.

<VirtualList
  items={query.data?.pages.flatMap((page) => page.items)}
  isError={query.isError}
  onRetry={() => query.fetchNextPage()}
  /* … */
/>
``` `labels.retry` (padrão "Tentar de novo") nomeia o botão da nova
tentativa, e tem a mesma chave e o mesmo padrão nas peças de consulta:
traduzir o título sem poder traduzir o botão é pior do que não traduzir nada.

**A espera se anuncia em voz alta.** `aria-busy` num nó sem papel não é lido por
leitor de tela nenhum: ele descreve o estado de uma região, e só chega a quem já
está dentro dela. Quem esperava ouvia silêncio, e a chegada do dado, que troca a
tela inteira, também não dizia nada. As quatro irmãs publicam a mesma região viva
(`role="status" aria-live="polite"`, marcada com `data-rc-status`), que diz
"Carregando…" enquanto a consulta não volta e "Conteúdo carregado" quando ela
volta. Ela existe antes de o texto mudar e é o mesmo nó do primeiro ao último
estado: região que nasce já com o texto dentro não dispara anúncio nenhum.

## A revalidação: `isFetching` e `isRefetchError`

Os mesmos dois nomes e o mesmo desenho do `QueryBoundary`. Com `items` na mão,
**`isFetching`** deixa a lista na tela, marca a moldura com `aria-busy` e corre uma
barra fina no topo; sem dado, ele é a primeira busca, e quem desenha é o
carregando. **`isRefetchError`** com `items` na mão vence o `isError`: a lista
fica, e um aviso em tom de atenção acima diz que a tela está desatualizada, com
o botão do `onRetry`. Antes, a revalidação que falhava trocava a lista pelo aviso
de erro. Sem dado, é o erro de sempre.

`labels.refreshing`, `labels.refetchError` e `labels.stale` trocam os textos, e `classNames.refreshing` e `classNames.stale` vestem a barra e o aviso. A barra gruda no topo da moldura, e não rola com os itens.

## Partes

`classNames` veste cada parte sem ninguém alcançar o nó interno por `[&>div>div]`:

- **`list`**: a faixa de altura total que rola por dentro da moldura.
- **`item`**: a caixa posicionada de cada item, onde entra o que `renderItem`
  devolve.

`className` continua sendo a moldura, e é onde se tira a borda quando a lista é
de cartões soltos.

## O item interativo vem do `renderItem`

Não há `onItemClick`. Uma `<div>` que responde ao clique não responde ao Enter,
e uma lista de mil dessas é mil alvos que o teclado não alcança. Quem precisa de
item clicável devolve o alvo de verdade: `<Item interactive render={<a />}>` ou
`<Item interactive render={<button />}>`, que já trazem foco visível e cor de
passagem.

## Quando não usar

**Se o dado é tabular, use `DataTable`.** Ela já virtualiza (`maxHeight` mais
`virtual`), e leva junto o que uma lista não tem: coluna com cabeçalho,
ordenação, filtro que ignora acento, seleção e linha de totais alinhada com as
colunas. Uma listagem de pedidos montada com `VirtualList` é uma tabela
reconstruída à mão, e a primeira coisa que se perde é o alinhamento entre
colunas.

**Se a lista é curta, use `ScrollArea`.** Ela é a moldura de rolagem sem
virtualização nenhuma: nada de altura de item, nada de palpite, nada de
`aria-setsize`. Para os trinta avisos de um painel lateral, é a peça certa, e a
`VirtualList` ali só acrescenta uma prop obrigatória a mais e uma altura para
você adivinhar.

## No React Native

Não porta, e não é fila: **a plataforma já resolve**. A `FlatList` do React Native virtualiza de fábrica, e o `DataList` daqui já a usa por baixo. Uma peça nossa por cima seria embrulho de embrulho, e cobraria manutenção para reimplementar o que o sistema entrega, com pior desempenho, porque a `FlatList` roda parte do trabalho fora da ponte de JavaScript.

O que o web tinha de próprio, e que a `FlatList` não dá sozinha, são os quatro finais e a contagem honesta para o leitor de tela. Os dois já estão no `DataList`: use ele para lista longa que veio de consulta, e a `FlatList` crua para lista longa que você já tem na mão.

API

PropTipoPadrão
itemKeyobrigatória

Identidade do item, e nao so chave de React: e por ela que a altura medida segue o item quando a lista reordena ou filtra.

(item: Item, index: number) => stringsem padrão
itemsobrigatóriaItem[] | undefinedsem padrão
renderItemobrigatória

O que cada item mostra.

(item: Item, index: number) => ReactNodesem padrão
classNames

Classe por parte: `list` e a faixa de altura total que rola por dentro da moldura, `item` e a caixa posicionada de cada item.

Partial<Record<"item" | "list" | "refreshing" | "stale", string>>sem padrão
empty

O que aparece quando a consulta volta vazia.

{ title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; illustration?: ReactNode; }sem padrão
errorMessageReactNode"Não foi possível carregar a lista."
errorTitle

O titulo do aviso de erro.

ReactNode"Não foi possível carregar"
gap

Respiro entre um item e o proximo, em pixel.

numbersem padrão
getScrollElement

Quem rola, quando nao e a propria lista: o `window` para a pagina inteira, ou o elemento de um painel que ja rola por fora.

(() => ScrollTarget | null)sem padrão
isError

A consulta falhou.

booleansem padrão
isFetching

Ha uma busca correndo, inclusive a que revalida o dado que ja esta na tela - o `isFetching` do TanStack Query.

booleansem padrão
isHeader

Diz que o item e cabecalho de grupo, e nao linha de dado: ele rola com a lista, mas fica fora do `aria-setsize`, do `aria-posinset` e da contagem.

((item: Item, index: number) => boolean)sem padrão
isLoadingbooleansem padrão
isRefetchError

A ultima busca falhou, mas o dado anterior continua valido - o `isRefetchError` do TanStack Query.

booleansem padrão
itemHeight

O palpite de altura de um item, em pixel, ou uma funcao por indice.

number | ((index: number) => number)44
label

O nome da lista para o leitor de tela.

stringsem padrão
labels

Os textos da peca, para trocar o idioma: `retry` e o botao que executa o `onRetry` - a mesma chave em todas as pecas que resolvem os quatro finais -, e `count` a contagem que entra no nome da lista, colada ao `label`.

Partial<VirtualListLabels>sem padrão
maxHeight

Altura maxima da moldura.

string | numbersem padrão
measure

Cada item desenhado devolve a altura real, e a rolagem se corrige.

booleantrue
onRetry

Sem isto, o erro nao oferece nova tentativa.

(() => void)sem padrão
overscan

Quantos itens desenhar alem da moldura, de cada lado.

number10
ref

Recebe um `VirtualListHandle`: `scrollToIndex(index, { align, behavior })`, `scrollToOffset(pixels, { align, behavior })`, medido do topo da lista, e `scrollToTop()`.

Ref<VirtualListHandle>sem padrão
skeletonItems

Quantos itens falsos o carregando mostra.

number5
totalCount

Quantas linhas de dado existem de verdade, e nao quantas ja chegaram.

numbersem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.