Pular para o conteúdo
Ações

ScrollToTop

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

Numa lista que rola por dentro

  • Entrega 4800Rua das Acácias, 88
  • Entrega 4801Avenida Central, 1200
  • Entrega 4802Travessa do Porto, 7
  • Entrega 4803Rua Sete de Abril, 310
  • Entrega 4804Rua das Acácias, 88
  • Entrega 4805Avenida Central, 1200
  • Entrega 4806Travessa do Porto, 7
  • Entrega 4807Rua Sete de Abril, 310
  • Entrega 4808Rua das Acácias, 88
  • Entrega 4809Avenida Central, 1200
  • Entrega 4810Travessa do Porto, 7
  • Entrega 4811Rua Sete de Abril, 310
  • Entrega 4812Rua das Acácias, 88
  • Entrega 4813Avenida Central, 1200
  • Entrega 4814Travessa do Porto, 7
  • Entrega 4815Rua Sete de Abril, 310
  • Entrega 4816Rua das Acácias, 88
  • Entrega 4817Avenida Central, 1200
  • Entrega 4818Travessa do Porto, 7
  • Entrega 4819Rua Sete de Abril, 310
  • Entrega 4820Rua das Acácias, 88
  • Entrega 4821Avenida Central, 1200
  • Entrega 4822Travessa do Porto, 7
  • Entrega 4823Rua Sete de Abril, 310
  • Entrega 4824Rua das Acácias, 88
  • Entrega 4825Avenida Central, 1200
  • Entrega 4826Travessa do Porto, 7
  • Entrega 4827Rua Sete de Abril, 310
  • Entrega 4828Rua das Acácias, 88
  • Entrega 4829Avenida Central, 1200
  • Entrega 4830Travessa do Porto, 7
  • Entrega 4831Rua Sete de Abril, 310
  • Entrega 4832Rua das Acácias, 88
  • Entrega 4833Avenida Central, 1200
  • Entrega 4834Travessa do Porto, 7
  • Entrega 4835Rua Sete de Abril, 310
  • Entrega 4836Rua das Acácias, 88
  • Entrega 4837Avenida Central, 1200
  • Entrega 4838Travessa do Porto, 7
  • Entrega 4839Rua Sete de Abril, 310
Importar
import { ScrollToTop } from '@rivocode/ui'

Quando usar

O botão flutuante "Voltar ao topo". Ele só existe depois que a pessoa desce além de um limite, fica no canto da janela, e leva de volta ao começo de uma página longa: uma listagem de muitas linhas, um relatório, um termo.

<ScrollToTop />

É o IconButton da casa, em pílula e com sombra, com a seta para cima e o nome "Voltar ao topo", preso ao canto de baixo à direita por um Affix.

Quando aparece

threshold é quantos pixels a pessoa precisa descer: 400 por padrão. Acima disso o botão não existe, e não só fica invisível: ele não entra no Tab nem na lista de botões do leitor de tela. Ele entra com a animação curta de aparecer, que desliga sozinha quando o sistema pede para reduzir movimento.

O que o clique faz

Rola até o topo, suave, ou num salto quando o sistema pede para reduzir movimento. E leva o foco para o começo da página: o <main>, ou o <body> quando não há <main>. Sem isso o foco ficaria no botão, que some assim que a página chega ao topo, e quem navega por teclado voltaria ao fim da página no próximo Tab. O destino ganha tabindex="-1" só enquanto tem o foco.

focusTarget escolhe outro destino, como o <h1> da tela. onScrollToTop é chamado depois que a subida começou.

Numa caixa que rola

target troca a janela por uma caixa com rolagem própria: é nela que a distância é medida, é ela que sobe, e é para ela que o foco vai. Com strategy="absolute", o botão gruda no canto do ancestral posicionado em vez do canto da janela.

const [caixa, setCaixa] = useState<HTMLDivElement | null>(null)

<div className="relative">
  <div ref={setCaixa} className="h-96 overflow-y-auto">…</div>
  <ScrollToTop target={caixa} strategy="absolute" position={{ bottom: 16, right: 16 }} />
</div>

Passe o elemento, guardado num estado, e não o ref: o botão precisa saber quando a caixa chegou para começar a medir.

Posição e aparência

position, strategy, layer, withinPortal e reserveSpace são os do Affix e passam direto para ele. label troca o nome, icon troca a seta, tooltip mostra o nome numa dica, e size e variant são os do IconButton. className veste a camada que gruda e classNames.button, o botão.

O botão reserva a própria altura no scroll-padding-bottom da página, então o foco do teclado não para escondido atrás dele. A explicação está no Affix.

Quando não usar

  • Página curta, que cabe em duas telas, não precisa dele: a pessoa volta rolando, e o botão só ocupa o canto.
  • Pular para uma seção é TableOfContents. O botão só conhece o topo; o índice conhece o caminho inteiro.
  • Outra ação que acompanha a rolagem (assinar, salvar, finalizar a compra) é Affix com o Button dentro. O ScrollToTop é só a subida.
  • Ações sobre linhas selecionadas são ActionBar, que aparece pela seleção, e não pela rolagem.

No React Native

Não porta, por decisão: o celular já sobe a lista de fábrica. No iOS, tocar na barra de status leva ao topo a ScrollView e a FlatList da tela (é o scrollsToTop, ligado por padrão), e no Expo Router e no React Navigation tocar de novo na aba em que a pessoa já está faz o mesmo, com o useScrollToTop(ref) na lista. Um botão flutuante por cima disso seria um terceiro caminho para o mesmo gesto, cobrindo o canto onde mora a ação principal da tela.

Não há foco a devolver: a navegação por toque não tem um Tab que continue do fim da página.

API

PropTipoPadrão
classNamesPartial<Record<"button", string>>sem padrão
focusTarget

Para onde o foco vai depois de subir.

HTMLElement | nullsem padrão
icon

O icone.

ReactNodesem padrão
label

O nome do botao, que o leitor de tela anuncia e a dica mostra.

string"Voltar ao topo"
layer

A camada de empilhamento, lida de `--rc-z-*`.

AffixLayersem padrão
onScrollToTop

Chamado depois que a subida comecou e o foco ja foi movido.

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

Onde a peca gruda, em cada lado: numero e pixel, texto e qualquer medida do CSS (`"var(--rc-pad-panel)"`, `"2rem"`).

AffixPositionsem padrão
reserveSpace

Reserva a altura da peca no `scroll-padding` da pagina, do lado em que ela gruda, para o foco do teclado nunca parar escondido atras dela.

booleansem padrão
showWhenOutOfView

So aparece quando este elemento sai da tela: o botao "Comprar" do topo da pagina que vira barra grudada quando a pessoa rola, o titulo que vira faixa.

RefObject<Element | null>sem padrão
size

O lado do quadrado do botao, lido de `--rc-control-*`.

"lg""md""sm""md"
strategy

Em relacao a que a peca gruda.

"absolute" | "fixed"sem padrão
target

A caixa que rola, quando nao e a janela.

HTMLElement | nullsem padrão
threshold

Quantos pixels a pessoa precisa descer para o botao aparecer.

number400
tooltip

Mostra o `label` numa dica ao pousar o ponteiro ou focar pelo teclado.

booleanfalse
variant

A variante do `Button` por baixo.

"danger""ghost""outline""primary""secondary"null"secondary"
withinPortal

Renderiza no container de portal do `RivoProvider`, fora da arvore.

booleansem 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.