ScrollArea
Lista longa
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
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasses por parte. | Partial<Record<"viewport", string>> | sem padrão |
fadeEsmaece 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. | boolean | sem padrão |
horizontal0.4.0Rolagem de lado tambem. | boolean | sem padrão |
overflowEdgeThreshold0.4.0Quantos 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.0Troca 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 |
viewportRefO 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.