Pular para o conteúdo
Estrutura

ScrollArea

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

Lista longa

Importar
import { ScrollArea } from '@rivocode/ui'

Quando usar

Área de rolagem com barra própria.

Serve para quando a barra do sistema atrapalha o desenho: no Windows ela ocupa largura e empurra o conteúdo, e a diferença entre plataformas aparece na tela. Para rolagem comum de página, overflow-y-auto continua sendo mais barato.

<ScrollArea className="h-48">
  {messages.map((message) => (
    <p key={message.id}>{message.text}</p>
  ))}
</ScrollArea>

horizontal liga a barra de lado também, para tabela larga e fila de cartões.

fade esmaece a borda de cima e a de baixo quando há conteúdo escondido daquele lado. Como a barra só aparece ao passar o ponteiro, é o esmaecido que avisa que a lista continua. Ele cresce com o que falta rolar, até 1,5rem, e some na ponta. É máscara, e não cor, então funciona sobre qualquer fundo; e o item que recebe foco pelo Tab para longe da borda esmaecida. O SidebarContent já vem com ele.

<ScrollArea fade className="h-64">
  {items.map((item) => (
    <p key={item.id}>{item.name}</p>
  ))}
</ScrollArea>

classNames.viewport veste a caixa que rola, que é a que recebe o foco quando há o que rolar.

Sem horizontal, o conteúdo tem a largura da moldura e encolhe com ela: truncate corta a linha com reticências quando o painel estreita, sem [&>div>div]:!min-w-0 nenhum. Com horizontal, ele volta a ter a largura do que traz dentro, que é o que dá à barra de lado o que rolar.

Quando não usar

Para rolagem comum de página, a do navegador basta e custa menos: a ScrollArea só se paga quando a barra do sistema atrapalha o desenho.

Lista com milhares de itens é VirtualList, que desenha só o que cabe na moldura: a ScrollArea troca a barra, e continua montando cada linha no DOM. Tabela longa já tem a mesma engrenagem dentro do DataTable.

No React Native

Traduz, e muda de assunto no caminho. No web a peça existe pela barra: a do sistema ocupa largura no Windows e desenha diferente em cada plataforma. No celular a barra é do sistema e fica sendo, e o problema de rolagem que dói é outro: o teclado cobre o campo. Formulário no fim da tela some debaixo dele, e o botão de enviar fica escondido até alguém fechar o teclado para achá-lo.

Então o ScrollArea nativo é a tela de formulário. Por baixo é o KeyboardAwareScrollView da react-native-keyboard-controller: ao focar um campo, a rolagem anda até ele parar bottomOffset pontos acima do teclado (16 por padrão), no mesmo quadro em que o teclado sobe, nos dois sistemas. O toque num item da lista não fecha o teclado (keyboardShouldPersistTaps="handled").

<ScrollArea
  contentContainerClassName="gap-4 p-5"
  footer={<Button onPress={salvar}>Salvar</Button>}
>
  <Field label="Descrição">…</Field>
</ScrollArea>

O footer é a ação presa embaixo da rolagem, e ele sobe junto com o teclado: o botão de enviar fica sempre à vista. A altura dele entra na conta de onde o campo em foco para, então nenhum campo fica escondido atrás do botão. Com o "reduzir movimento" ligado, o rodapé pula direto para cima do teclado em vez de acompanhá-lo; a rolagem até o campo continua, porque sem ela o campo fica coberto.

Não há horizontal: fila de cartões que rola de lado é ScrollView puro, e não tem campo para o teclado cobrir. A react-native-keyboard-controller é peer do pacote, e o KeyboardProvider que ela pede já vem dentro do RivoProvider.

O conteúdo que rola se veste pelo contentContainerClassName, o nome que a ScrollView já dá a ele, e a faixa do footer pelo classNames.footer.

No iOS e no Android. Ao chegar no fim da rolagem, o iOS estica com mola e o Android estica a borda (Android 12 ou mais novo) ou mostra o brilho (até o 11). É o gesto do sistema, e a peça não o troca.

API

PropTipoPadrão
classNames

Classes por parte.

Partial<Record<"viewport", string>>sem padrão
fade

Esmaece a borda de cima e a de baixo quando ha conteudo escondido daquele lado: o aviso de que a lista continua, ja que a barra so aparece no passar do ponteiro.

booleansem padrão
horizontal0.4.0

Rolagem de lado tambem.

booleansem padrão
overflowEdgeThreshold0.4.0

Quantos pixels de rolagem passam antes de os atributos de borda transbordada entrarem.

number | Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }>0
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, ScrollAreaRootState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
viewportRef

O elemento que rola, e nao a moldura que o `ref` alcanca: para o `scrollTo({ top: 0 })` ao trocar de filtro e para o `root` de um `IntersectionObserver`.

Ref<HTMLDivElement>sem 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.