Scroll Pane

El ScrollPane es un componente compuesto que maneja desplazamientos responsivos en listas que se desbordan dentro de un contenedor. Proporciona superposiciones de gradiente, flechas de navegación opcionales y funcionalidad de desplazamiento a un elemento.

Lista de Cards horizontales (Desktop)

Lista de Cards horizontales (Mobile)

Lista de Cards con scroll vertical

Segmented Control scrollables

Contenido 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;

Implementación

Instalá el componente via terminal.

npm install @nimbus-ds/scroll-pane

ScrollPane

Definición

El componente Scroll Pane permite contener y visualizar contenido que excede el alto o ancho disponible de su contenedor, mediante un scroll interno. Es ideal para preservar el contexto visual del usuario dentro de un flujo principal, permitiendo el desplazamiento aislado de secciones específicas sin impactar el layout global de la página. La presencia de gradientes que suavizan los límites del contenedor ayuda al usuario a percibir que hay más contenido disponible.

Cuándo usar

Para mostrar contenido extenso (múltiples opciones, múltiples módulos de texto, etc.) dentro de un contenedor limitado, como paneles laterales, modales o carruseles de cards.
Cuando es necesario evitar que el scroll principal de la página se vea afectado por secciones con mucho contenido.
Para mantener elementos clave visibles (como encabezados o botones fijos) mientras el resto del contenido se desplaza.
En mobile, para mostrar contenido comparativo o múltiples módulos de contenido en cards.

Cuándo no usar

Cuando todo el contenido puede mostrarse sin necesidad de scroll, especialmente en dispositivos móviles. (Si hay 2 o menos módulos de contenido, no usar Scroll Pane).
En situaciones donde múltiples scrolls en la misma vista pueden generar confusión o dificultar la navegación (scrolls anidados innecesarios).
Para reemplazar el scroll natural del navegador en vistas principales de página.

Criterios de productividad y usabilidad

Mantiene el foco del usuario al aislar el scroll de ciertas secciones sin desorientarlo en el flujo global.
Minimiza el cambio de contexto, permitiendo trabajar sobre contenido detallado sin salir del entorno principal.
Reduce pantallas intermedias o modales innecesarios, mostrando más contenido sin interrumpir la navegación.

Buenas prácticas de accesibilidad

Asegurar navegación con teclado: el usuario debe poder acceder a todo el contenido con Tab y flechas.
Usar roles ARIA apropiados como aria-label para describir el área scrollable si es relevante para la navegación.
No ocultar el foco visual dentro del contenido que hace scroll.
Definir áreas de tap adecuadas para scrollbars customizadas en mobile.

Anatomía

El Scroll Pane está compuesto por:

Contenedor visible con dimensiones definidas.
Área de contenido scrollable.
Scrollbar vertical (nativa o personalizada).

Dependencias

Puede incluir cualquier componente de Nimbus como Text, Card, Button, etc.
Se recomienda que su implementación esté dentro de layouts como Modal, Sidebar, o secciones de la página.

Variantes

Con contenido simple: texto largo, listas, cards.
Con scroll automático: ajusta el scroll al añadir elementos dinámicamente (como notificaciones o mensajes).

Do and Don'ts

✅ Do

Usar scroll interno para contenido largo sin perder el encabezado o botones de acción.
Combinar con focus automático para mejorar la productividad.

❌ Don't

No anidar múltiples Scroll Pane.
No ocultar contenido importante que no es obvio que requiere scroll.
No reemplazar el scroll nativo si el contenido principal puede mostrarse completo.

Props

Props adicionales se pasan al elemento <ScrollPane>. Ver documentación del div para una lista de props aceptadas por el 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.