Pular para o conteúdo principal

List

Container para organizar itens de lista, especialmente TransactionListItem. Fornece a estrutura base para listas de transações, notificações e outros itens que seguem o padrão de design do Ocean.

Importação​

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

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

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

Importação de tipos TypeScript​

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

// Uso em componente customizado
const MyList: React.FC<ListProps> = (props) => {
  return <List {...props} />;
};

Playground Interativo​

Explore o componente List no playground interativo do Storybook:

🚀 Abrir no Storybook

Uso básico​

<List>
  <TransactionListItem>Item simples 1</TransactionListItem>
  <TransactionListItem>Item simples 2</TransactionListItem>
  <TransactionListItem>Item simples 3</TransactionListItem>
</List>

Variações​

Lista com ícones​

Use ícones para melhor identificação visual dos itens:

<List>
  <TransactionListItem icon={<StarOutline />}>
    Item com estrela
  </TransactionListItem>
  <TransactionListItem icon={<Reply />}>Item com resposta</TransactionListItem>
  <TransactionListItem icon={<LockClosed />}>
    Item com cadeado
  </TransactionListItem>
</List>
🚀 Abrir no Storybook

Lista com valores​

Para transações financeiras ou valores numéricos:

<List>
  <TransactionListItem value="R$ 100,00" positive>
    Receita
  </TransactionListItem>
  <TransactionListItem value="R$ 50,00">Despesa</TransactionListItem>
  <TransactionListItem value="R$ 25,50" positive>
    Crédito
  </TransactionListItem>
</List>
🚀 Abrir no Storybook

Lista com tags e informações adicionais​

Para categorização e detalhes extras:

<List>
  <TransactionListItem
    level2="Informação secundária"
    tags="Pendente"
    time="10:30"
  >
    Item com tag
  </TransactionListItem>
  <TransactionListItem level2="Outra informação" tags="Aprovado" time="14:15">
    Item aprovado
  </TransactionListItem>
</List>
🚀 Abrir no Storybook

Lista com subitens​

Para mostrar hierarquia e detalhes aninhados:

<List>
  <TransactionListItem
    withChevron
    subItens={
      <List>
        <TransactionListItem level2="Detalhe 1">Subitem 1</TransactionListItem>
        <TransactionListItem level2="Detalhe 2">Subitem 2</TransactionListItem>
      </List>
    }
  >
    Item principal com subitens
  </TransactionListItem>
</List>
🚀 Abrir no Storybook

Exemplos práticos​

Lista de transações​

<List>
  <TransactionListItem
    icon={<StarOutline />}
    level2="Banco do Brasil"
    value="R$ 150,00"
    time="09:30"
    positive
  >
    Transferência recebida
  </TransactionListItem>
  <TransactionListItem
    icon={<Reply />}
    level2="Pagamento"
    value="R$ 75,50"
    time="14:20"
  >
    Compra no cartão
  </TransactionListItem>
</List>

Lista de notificações​

<List>
  <TransactionListItem
    icon={<LockClosed />}
    level2="Segurança"
    tags="Importante"
    time="10:15"
  >
    Nova tentativa de login
  </TransactionListItem>
  <TransactionListItem level2="Sistema" tags="Info" time="08:45">
    Atualização disponível
  </TransactionListItem>
</List>

API​

Props​

PropTipoPadrãoDescrição
childrenReact.ReactNode-Conteúdo da lista (geralmente TransactionListItem)
classNamestring-Classes CSS adicionais para customização

Elementos HTML suportados​

O componente List é baseado no elemento <div> e suporta todos os atributos padrão de div.

Acessibilidade​

  • ✅ Estrutura semântica correta para listas
  • ✅ Suporte a navegação por teclado
  • ✅ Compatível com screen readers
  • ✅ Estados de foco adequados nos itens
TeclaFunção
TabNavega entre os itens da lista
Space / EnterAtiva itens interativos
Arrow Up/DownNavega verticalmente (quando aplicável)

Melhores práticas​

✅ Faça​

  • Use TransactionListItem como filhos do componente List
  • Mantenha consistência na estrutura dos itens dentro da mesma lista
  • Use ícones apropriados para melhor identificação visual
  • Use level2, level3 e level4 para informações hierárquicas
  • Use value para valores monetários ou numéricos
  • Use positive para valores positivos (receitas, créditos)
  • Use tags para status ou categorização
  • Use time para timestamps ou horários

❌ Não faça​

  • Não misture diferentes tipos de conteúdo na mesma lista
  • Não omita informações importantes de acessibilidade
  • Não use listas muito longas sem paginação ou virtualização
  • Não negligencie o estado de carregamento para dados dinâmicos

Estrutura e Organização​

  • Use TransactionListItem: Principal componente para itens da lista
  • Consistência: Mantenha padrão similar entre itens da mesma lista
  • Hierarquia: Use subItens para mostrar detalhes adicionais
  • Interatividade: Use withChevron para indicar itens expansíveis

Estados e Feedback​

  • Loading: Use isLoading para indicar carregamento de dados
  • Feedback visual: Forneça indicações visuais para diferentes estados
  • Responsividade: Adapte layout para diferentes tamanhos de tela

Visão geral de todas as variações​

Veja todas as variações do List em ação:

🚀 Abrir no Storybook

Documentação Completa​

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

No Storybook você encontrará:

  • ✅ Controles interativos para testar todas as props
  • ✅ API gerada automaticamente com tipagem completa
  • ✅ Exemplos visuais de todas as variações e casos de uso
  • ✅ Playground para experimentação rápida

CSS Classes​

O componente gera as seguintes classes CSS:

ClasseDescrição
.ods-listClasse base aplicada ao container da lista