ScrollArea

Avatar de TanStack VirtualTanStack VirtualGitLab
Um container de rolagem flexível com suporte a virtualização.

Uso

O componente ScrollArea cria containers roláveis com virtualização opcional para listas grandes.

Itens

Use a prop items como um array e renderize cada item usando o slot padrão:

Item 1
Description for item 1
Item 2
Description for item 2
Item 3
Description for item 3
Item 4
Description for item 4
Item 5
Description for item 5
Item 6
Description for item 6
Item 7
Description for item 7
Item 8
Description for item 8
Item 9
Description for item 9
Item 10
Description for item 10
Item 11
Description for item 11
Item 12
Description for item 12
Item 13
Description for item 13
Item 14
Description for item 14
Item 15
Description for item 15
Item 16
Description for item 16
Item 17
Description for item 17
Item 18
Description for item 18
Item 19
Description for item 19
Item 20
Description for item 20
Item 21
Description for item 21
Item 22
Description for item 22
Item 23
Description for item 23
Item 24
Description for item 24
Item 25
Description for item 25
Item 26
Description for item 26
Item 27
Description for item 27
Item 28
Description for item 28
Item 29
Description for item 29
Item 30
Description for item 30
Você também pode usar o slot padrão sem a prop items para renderizar conteúdo rolável personalizado diretamente.

Orientação

Use a prop orientation para alterar a direção da rolagem. O padrão é vertical.

Item 1
Description for item 1
Item 2
Description for item 2
Item 3
Description for item 3
Item 4
Description for item 4
Item 5
Description for item 5
Item 6
Description for item 6
Item 7
Description for item 7
Item 8
Description for item 8
Item 9
Description for item 9
Item 10
Description for item 10
Item 11
Description for item 11
Item 12
Description for item 12
Item 13
Description for item 13
Item 14
Description for item 14
Item 15
Description for item 15
Item 16
Description for item 16
Item 17
Description for item 17
Item 18
Description for item 18
Item 19
Description for item 19
Item 20
Description for item 20
Item 21
Description for item 21
Item 22
Description for item 22
Item 23
Description for item 23
Item 24
Description for item 24
Item 25
Description for item 25
Item 26
Description for item 26
Item 27
Description for item 27
Item 28
Description for item 28
Item 29
Description for item 29
Item 30
Description for item 30

Virtualizar

Use a prop virtualize para renderizar apenas os itens que estão em exibição no momento, melhorando significativamente o desempenho ao trabalhar com grandes conjuntos de dados.

Quando a virtualização está habilitada, personalize o espaçamento por meio das opções da prop virtualize, como gap, paddingStart e paddingEnd. Caso contrário, use a prop ui para aplicar classes como gap p-4 no slot viewport.
Se todos os seus itens têm a mesma altura, defina skipMeasurement como true na prop virtualize para pular a medição de DOM por item e usar o estimateSize. Isso melhora significativamente o desempenho em listas grandes e uniformes.

Sombra 4.9+

Use a prop shadow para exibir sombras de esmaecimento nas bordas roláveis, indicando que há mais conteúdo disponível na direção da rolagem. O esmaecimento acompanha automaticamente a orientation e só aparece quando o conteúdo transborda.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

Passe um objeto para a prop shadow para configurar o tamanho do esmaecimento, ex.: :shadow="{ size: 48 }".

Exemplos

Como layout masonry

Use a prop virtualize com as opções lanes, gap e estimateSize para criar layouts masonry no estilo Pinterest com itens de altura variável.

Para um desempenho ideal, defina estimateSize próximo da altura média dos seus itens. Aumentar o overscan melhora a suavidade da rolagem, mas renderiza mais itens fora da tela.

Com faixas responsivas

Você pode usar os composables useWindowSize (baseado na viewport) ou useElementSize (baseado no container) para tornar as lanes reativas.

Com elemento de rolagem externo Soon

Passe uma função getScrollElement na prop virtualize para virtualizar em relação a um container de rolagem ancestral em vez da própria viewport do componente. Defina scrollMargin como o deslocamento da lista em relação ao início do elemento de rolagem (ex.: a altura do conteúdo acima dela).

Members

This header scrolls away with the cards, sharing one scrollbar.

0 members
0/0
Como o container controla a rolagem, os botões de busca e "Topo" da barra de ferramentas o rolam diretamente com container.scrollTo.
A prop shadow não tem efeito nesse modo, já que o root não controla mais a rolagem. Em vez disso, aplique o seu próprio esmaecimento ao container de rolagem.

Com rolagem programática

Você pode usar o virtualizer exposto para controlar a posição de rolagem programaticamente.

Com rolagem infinita

Você pode usar o composable useInfiniteScroll para carregar mais dados conforme o usuário rola.

Este exemplo usa useLazyFetch com server: false para buscar os dados no cliente sem bloquear a renderização inicial. O estado de carregamento verifica os status pending e idle para exibir um indicador de carregamento antes e durante a busca. Páginas adicionais são carregadas conforme o usuário rola.

Com slot padrão

Você pode usar o slot padrão sem a prop items para renderizar conteúdo rolável personalizado diretamente.

Seção 1
Conteúdo personalizado sem usar a prop items.
Seção 2
Conteúdo personalizado sem usar a prop items.
Seção 3
Conteúdo personalizado sem usar a prop items.
Seção 4
Conteúdo personalizado sem usar a prop items.
Seção 5
Conteúdo personalizado sem usar a prop items.
Seção 6
Conteúdo personalizado sem usar a prop items.

API

Props

Prop Default Type
as'div'any

The element or component this component should render as.

orientation'vertical' "vertical" | "horizontal"

The scroll direction.

items T[]

Array of items to render.

virtualizefalseboolean | ScrollAreaVirtualizeOptions

Enable virtualization for large lists.

shadowfalseboolean | { size?: number ; } | undefined

Display fade shadows on the scrollable edges to indicate more content. Pass an object to configure the shadow size (in px).

ui { root?: SlotClass; viewport?: SlotClass; item?: SlotClass; }

Slots

Slot Type
default{ item: T; index: number; virtualItem?: VirtualItem | undefined; } | { item: T; index: 0; }

Emits

Event Type
scroll[isScrolling: boolean]

Expose

Você pode acessar a instância tipada do componente usando useTemplateRef.

<script setup lang="ts">
const scrollArea = useTemplateRef('scrollArea')

// Scroll to a specific item
function scrollToItem(index: number) {
  scrollArea.value?.virtualizer?.scrollToIndex(index, { align: 'center' })
}
</script>

<template>
  <NScrollArea ref="scrollArea" :items="items" virtualize />
</template>

Isso dará a você acesso ao seguinte:

NameTypeDescription
$elHTMLElementThe root element of the component.
virtualizerRef<Virtualizer> | undefinedThe TanStack Virtual virtualizer instance (undefined if virtualization is disabled).

Tema

app.config.ts
export default defineAppConfig({
  ui: {
    scrollArea: {
      slots: {
        root: 'relative outline-accent/25 focus-visible:outline-3',
        viewport: 'relative flex',
        item: ''
      },
      variants: {
        orientation: {
          vertical: {
            root: 'overflow-y-auto overflow-x-hidden',
            viewport: 'flex-col',
            item: ''
          },
          horizontal: {
            root: 'overflow-x-auto overflow-y-hidden',
            viewport: 'flex-row',
            item: ''
          }
        },
        externalScroll: {
          true: {
            root: 'overflow-visible'
          }
        }
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        scrollArea: {
          slots: {
            root: 'relative outline-accent/25 focus-visible:outline-3',
            viewport: 'relative flex',
            item: ''
          },
          variants: {
            orientation: {
              vertical: {
                root: 'overflow-y-auto overflow-x-hidden',
                viewport: 'flex-col',
                item: ''
              },
              horizontal: {
                root: 'overflow-x-auto overflow-y-hidden',
                viewport: 'flex-row',
                item: ''
              }
            },
            externalScroll: {
              true: {
                root: 'overflow-visible'
              }
            }
          }
        }
      }
    })
  ]
})

Changelog

No recent changes

Marquee

Um componente para criar conteúdo com rolagem infinita.

Table

Um elemento de tabela responsivo para exibir dados em linhas e colunas.