Scroll Pane

O ScrollPane é um componente composto que gerencia deslocamentos responsivos em listas que transbordam dentro de um contêiner. Fornece sobreposições de gradiente, setas de navegação opcionais e funcionalidade de deslocamento para um elemento.

Lista de Cards horizontais (Desktop)

Lista de Cards horizontais (Mobile)

Lista de Cards com scroll vertical

Segmented Control roláveis

Conteúdo grande de cards

import React from "react";
import {
  ScrollPane,
  Card,
  Text,
  Button,
  IconButton,
  Box,
} from "@nimbus-ds/components";
import { ChevronRightIcon, ChevronLeftIcon } from "@nimbus-ds/icons";

const Example: React.FC = () => (
  <Box maxWidth="100%">
    <ScrollPane
      direction="horizontal"
      scrollPaneArrowEnd={
        <ScrollPane.ArrowHorizontalEnd>
          <IconButton source={<ChevronRightIcon />} />
        </ScrollPane.ArrowHorizontalEnd>
      }
      scrollPaneArrowStart={
        <ScrollPane.ArrowHorizontalStart>
          <IconButton source={<ChevronLeftIcon />} />
        </ScrollPane.ArrowHorizontalStart>
      }
      showArrows
      showGradients
      showScrollbar
      scrollToItemOnClick={false}
    >
      {Array.from({ length: 10 }).map((_, index) => (
        <ScrollPane.Item key={index} padding="2">
          <Card padding="base">
            <Text fontSize="base" fontWeight="bold">
              Card {index + 1}
            </Text>
            <Text color="neutral-textLow" fontSize="caption">
              This is a sample card with some content that demonstrates the
              scroll functionality.
            </Text>
            <Button>Action</Button>
          </Card>
        </ScrollPane.Item>
      ))}
    </ScrollPane>
  </Box>
);

export default Example;

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/scroll-pane

ScrollPane

Definição

O componente Scroll Pane permite conter e visualizar conteúdo que excede a altura ou largura disponível de seu contêiner, através de um scroll interno. É ideal para preservar o contexto visual do usuário dentro de um fluxo principal, permitindo o deslocamento isolado de seções específicas sem impactar o layout global da página. A presença de gradientes que suavizam os limites do contêiner ajuda o usuário a perceber que há mais conteúdo disponível.

Quando usar

Para mostrar conteúdo extenso (múltiplas opções, múltiplos módulos de texto, etc.) dentro de um contêiner limitado, como painéis laterais, modais ou carrosséis de cards.
Quando é necessário evitar que o scroll principal da página seja afetado por seções com muito conteúdo.
Para manter elementos chave visíveis (como cabeçalhos ou botões fixos) enquanto o resto do conteúdo se desloca.
No mobile, para mostrar conteúdo comparativo ou múltiplos módulos de conteúdo em cards.

Quando não usar

Quando todo o conteúdo pode ser mostrado sem necessidade de scroll, especialmente em dispositivos móveis. (Se há 2 ou menos módulos de conteúdo, não usar Scroll Pane).
Em situações onde múltiplos scrolls na mesma visualização podem gerar confusão ou dificultar a navegação (scrolls aninhados desnecessários).
Para substituir o scroll natural do navegador em visualizações principais de página.

Critérios de produtividade e usabilidade

Mantém o foco do usuário ao isolar o scroll de certas seções sem desorientá-lo no fluxo global.
Minimiza a mudança de contexto, permitindo trabalhar sobre conteúdo detalhado sem sair do ambiente principal.
Reduz telas intermediárias ou modais desnecessários, mostrando mais conteúdo sem interromper a navegação.

Boas práticas de acessibilidade

Assegurar navegação com teclado: o usuário deve poder acessar todo o conteúdo com Tab e setas.
Usar roles ARIA apropriados como aria-label para descrever a área rolável se for relevante para a navegação.
Não ocultar o foco visual dentro do conteúdo que faz scroll.
Definir áreas de toque adequadas para scrollbars customizadas no mobile.

Anatomia

O Scroll Pane é composto por:

Contêiner visível com dimensões definidas.
Área de conteúdo rolável.
Scrollbar vertical (nativa ou personalizada).

Dependências

Pode incluir qualquer componente do Nimbus como Text, Card, Button, etc.
Recomenda-se que sua implementação esteja dentro de layouts como Modal, Sidebar, ou seções da página.

Variantes

Com conteúdo simples: texto longo, listas, cards.
Com scroll automático: ajusta o scroll ao adicionar elementos dinamicamente (como notificações ou mensagens).

Do and Don'ts

✅ Do

Usar scroll interno para conteúdo longo sem perder o cabeçalho ou botões de ação.
Combinar com foco automático para melhorar a produtividade.

❌ Don't

Não aninhar múltiplos Scroll Pane.
Não ocultar conteúdo importante que não é óbvio que requer scroll.
Não substituir o scroll nativo se o conteúdo principal pode ser mostrado completo.

Props

Props adicionais são passadas para o elemento <ScrollPane>. Veja a documentação do div para uma lista de props aceitas pelo elemento <ScrollPane>.

ScrollPane

Name	Type	Default	Description
children	React.ReactNode		The content to be rendered inside the scroll pane
showGradients	boolean	'true'	Whether to show gradient overlays when content overflows
showArrows	boolean	'false'	Whether to show navigation arrows for scrolling
showScrollbar	boolean	'true'	Whether to show the scrollbar
direction	'horizontal' 'vertical'	'horizontal'	The direction of the scroll (horizontal or vertical)
scrollToItemOnClick	boolean	'true'	Whether items should scroll into view when clicked
scrollPaneArrowStart	React.ReactNode		Custom arrow component to render at the start of the scroll area
scrollPaneArrowEnd	React.ReactNode		Custom arrow component to render at the end of the scroll area

ScrollPane.Item

Name	Type	Description
children	React.ReactNode	The content to be rendered inside the scroll pane item
className	string	Custom class name for styling
style	object	Custom inline styles
onClick	object	Callback fired when the item is clicked

ScrollPane.ArrowHorizontalStart

Name	Type	Default	Description
children	React.ReactNode		Represents all of the things React can render. Where {@link ReactElement} only represents JSX, `ReactNode` represents everything that can be rendered.

ScrollPane.ArrowHorizontalEnd

Name	Type	Default	Description
children	React.ReactNode		Represents all of the things React can render. Where {@link ReactElement} only represents JSX, `ReactNode` represents everything that can be rendered.

ScrollPane.ArrowVerticalStart

Name	Type	Default	Description
children	React.ReactNode		Represents all of the things React can render. Where {@link ReactElement} only represents JSX, `ReactNode` represents everything that can be rendered.

ScrollPane.ArrowVerticalEnd

Name	Type	Default	Description
children	React.ReactNode		Represents all of the things React can render. Where {@link ReactElement} only represents JSX, `ReactNode` represents everything that can be rendered.