Skip to main content

DotPagination

O componente DotPagination é usado para navegação entre seções de conteúdo, especialmente em carrosséis, slideshows e wizards. Oferece uma interface visual simples com pontos clicáveis que indicam o progresso e permitem navegação direta.

Importação​

import { DotPagination } from '@useblu/ocean-react';

Importação específica (recomendado para tree-shaking)​

import { DotPagination } from '@useblu/ocean-react/DotPagination';

Importação de tipos TypeScript​

import type { IDotPagination } from '@useblu/ocean-react';

// Uso em componente customizado
const MyCarousel: React.FC<{ totalSlides: number }> = ({ totalSlides }) => {
  const [activeSlide, setActiveSlide] = React.useState(0);

  return (
    <DotPagination
      items={totalSlides}
      activeItem={activeSlide}
      onActiveChange={setActiveSlide}
    />
  );
};

Playground Interativo​

Explore o componente DotPagination no playground interativo do Storybook:

🚀 Abrir no Storybook

Documentação Completa​

Para documentação técnica detalhada, exemplos de uso e API completa, consulte o Storybook do DotPagination.

No Storybook você encontrará:

  • ✅ Controles interativos para testar todas as props
  • ✅ API gerada automaticamente com tipagem completa
  • ✅ Exemplos visuais de todas as variantes e estados
  • ✅ Playground para experimentação rápida

Uso básico​

<DotPagination items={4} activeItem={1} />

Tamanhos diferentes​

O DotPagination se adapta automaticamente ao número de itens:

🚀 Abrir no Storybook

Estados ativos​

Veja como o componente se comporta com diferentes posições ativas:

🚀 Abrir no Storybook

Exemplo interativo​

function InteractiveDotPagination() {
  const [activeItem, setActiveItem] = React.useState(0);

  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: '16px',
        alignItems: 'center',
      }}
    >
      <p>Item ativo: {activeItem + 1}</p>
      <DotPagination
        items={5}
        activeItem={activeItem}
        onActiveChange={setActiveItem}
      />
    </div>
  );
}

API​

Props​

PropTipoPadrãoDescrição
itemsnumber-Número total de pontos a serem exibidos
activeItemnumber-Índice do ponto ativo (baseado em 0)
onActiveChange(index: number) => void-Função chamada quando um ponto é clicado

Eventos​

  • onActiveChange: Disparado quando um ponto é clicado, recebe o índice do ponto como parâmetro

Classes CSS​

O componente utiliza as seguintes classes CSS que podem ser customizadas:

ClasseDescrição
.dot-paginationContainer principal do componente
.dot-pagination__dotCada ponto individual
.dot-pagination__dot--activeModificador para o ponto ativo

Acessibilidade​

  • ✅ Suporte completo a navegação por teclado
  • ✅ Estados de foco visíveis
  • ✅ Atributos ARIA apropriados para screen readers
  • ✅ Labels descritivos para cada ponto
  • ✅ Indicação do estado ativo para tecnologias assistivas
TeclaFunção
TabMove o foco entre os pontos
Space / EnterAtiva o ponto em foco

Melhores práticas​

✅ Faça​

  • Use para indicar progresso em wizards e formulários multi-etapa
  • Use em carrosséis e galerias de imagens
  • Mantenha o número de pontos razoável (máximo 8-10)
  • Implemente navegação por teclado ao usar com carrosséis
  • Use junto com controles de navegação anterior/próximo

❌ Não faça​

  • Não use para grandes quantidades de páginas (use paginação numérica)
  • Não omita o callback onActiveChange se a navegação for necessária
  • Não use como única forma de navegação em interfaces complexas
  • Não esqueça de sincronizar com o conteúdo correspondente

Casos de uso comuns​

Em carrosséis​

function ImageCarousel({ images }) {
  const [currentImage, setCurrentImage] = React.useState(0);

  return (
    <div>
      <img src={images[currentImage]} alt={`Imagem ${currentImage + 1}`} />
      <DotPagination
        items={images.length}
        activeItem={currentImage}
        onActiveChange={setCurrentImage}
      />
    </div>
  );
}

Em wizards​

function SetupWizard() {
  const [currentStep, setCurrentStep] = React.useState(0);
  const steps = ['Informações', 'Preferências', 'Confirmação'];

  return (
    <div>
      <h2>{steps[currentStep]}</h2>
      {/* Conteúdo do step */}
      <DotPagination
        items={steps.length}
        activeItem={currentStep}
        onActiveChange={setCurrentStep}
      />
    </div>
  );
}