Primitivelayout

Scroll Area

Stable

Primitive de layout para uma região rolável cujas barras pertencem ao design system. Composto sobre Base UI Scroll Area: a rolagem continua nativa — roda, toque e teclado —, e a barra do navegador dá lugar a uma barra fina no mesmo tom de scrollbar-quiet. As barras são escolhidas por eixo com scrollbars e ficam ao lado do viewport, não dentro dele. Tamanho, borda e raio são de quem usa, e o anel de foco é desenhado no mesmo elemento que carrega o raio.

Instalação

npx up-web-ds add scroll-area

Preview

Basic

Horizontal

Both

Fits

All states

Basic

Horizontal

Both

Fits

Usage

@/components/ui/scroll-area
import { ScrollArea } from '@/components/ui/scroll-area'
Scroll Area
<ScrollArea
  role="region"
  aria-label="Itens do catálogo"
  className="h-56 w-full max-w-xs rounded-lg border border-border"
>
  <ul className="flex flex-col p-4">
    {items.map((item) => (
      <li
        key={item.name}
        className="flex flex-col gap-0.5 border-b border-border py-2 last:border-b-0"
      >
        <span className="type-small font-medium">{item.name}</span>
        <span className="type-caption text-muted-foreground">
          {item.category}
        </span>
      </li>
    ))}
  </ul>
</ScrollArea>

Props

ScrollArea

Props de ScrollArea
PropTypeDefaultDescription
scrollbars"horizontal" | "vertical" | "both"'vertical'Which axes get a scrollbar. The content decides whether there is anything to scroll; this decides which bars are drawn when there is.
classNamestring | ((state: ScrollAreaRootState) => string | undefined)sem valor padrãoCSS class applied to the element, or a function that returns a class based on the component's state.
overflowEdgeThresholdnumber | Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }>0The threshold in pixels that must be passed before the overflow edge attributes are applied. Accepts a single number for all edges or an object to configure them individually.
renderReact.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ScrollAreaRootState>sem valor padrãoAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
styleReact.CSSProperties | ((state: ScrollAreaRootState) => React.CSSProperties | undefined)sem valor padrãoStyle applied to the element, or a function that returns a style object based on the component's state.

Estende ScrollAreaPrimitive.Root.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ScrollBar

Props de ScrollBar
PropTypeDefaultDescription
classNamestring | ((state: ScrollAreaScrollbarState) => string | undefined)sem valor padrãoCSS class applied to the element, or a function that returns a class based on the component's state.
keepMountedbooleanfalseWhether to keep the HTML element in the DOM when the viewport isn't scrollable.
orientation"horizontal" | "vertical"'vertical'Whether the scrollbar controls vertical or horizontal scroll.
renderReact.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ScrollAreaScrollbarState>sem valor padrãoAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
styleReact.CSSProperties | ((state: ScrollAreaScrollbarState) => React.CSSProperties | undefined)sem valor padrãoStyle applied to the element, or a function that returns a style object based on the component's state.

Estende ScrollAreaPrimitive.Scrollbar.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

Metadata

Notas de acessibilidade

Teclado verificado por teste: o viewport entra na sequência de tabulação exatamente quando há algo a rolar — conteúdo além da dobra que nenhuma parada de Tab alcança é conteúdo que quem usa teclado nunca vê — e sai dela quando o conteúdo cabe, porque uma parada que não faz nada é uma parada a mais para atravessar. Com foco, as setas rolam o viewport, verificado em navegador, e o anel de foco aparece na raiz, que carrega o raio e a borda de quem usa; a origem desenhava o anel no viewport e copiava o raio com rounded-[inherit]. As barras ficam fora da sequência de tabulação: são affordance de ponteiro, e o viewport focado é a de teclado — uma parada, não três. Leitor de tela verificado por teste: o viewport não tem papel próprio, então uma região que merece ser anunciada recebe role="region" e nome na raiz, e é assim em todos os exemplos. As barras ficam ao lado do viewport e não dentro dele: a origem passava a barra horizontal como filho, e ela rolava junto com o conteúdo que devia controlar. Touch verificado em viewport de 375px com emulação de toque: o viewport é o alvo e mede bem acima de 24x24, o arrasto rola a região e a página não ganha rolagem horizontal. Reduced motion verificado em navegador com prefers-reduced-motion: reduce — não há deslocamento animado: a rolagem é do usuário, e as transições do anel e do polegar da barra são de sombra e cor, que permanecem.

Classificação

Layer
Primitive
Domínio
Domain-free (compartilhado)
Categoria
layout
Status
Stable

Origem e distribuição

Fonte
shadcn registry / scroll-area
Licença
MIT
Distribuição
Interna

Acessibilidade

  • Teclado: revisado
  • Leitor de tela: revisado
  • Touch: revisado
  • Reduced motion: revisado

Dependências

Pacotes
@base-ui/react
Ícones
Nenhum
Construído sobre
Nenhum
Usado por
Autocomplete