CardListItem

O CardListItem é um componente usado para exibir itens em listas organizadas, oferecendo uma estrutura consistente com título, descrição, ícones, tags e estados interativos. É ideal para listas de produtos, configurações, contatos ou qualquer conteúdo estruturado.

Importação

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

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

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

Importação de tipos TypeScript

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

// Uso em componente customizado
const MyComponent: React.FC<CardListItemProps> = (props) => {
  return <CardListItem {...props} />;
};

Playground Interativo

Explore o componente CardListItem 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 CardListItem.

No Storybook você encontrará:

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

Uso básico

Item simples

<CardListItem title="Título do Item" description="Descrição do item da lista" />

Item completo

<CardListItem
  title="Item Completo"
  description="Com ícones, tag e caption"
  caption="Caption adicional"
  tag="Novo"
/>

Tamanhos

O CardListItem oferece dois tamanhos:

🚀 Abrir no Storybook

Small

• Mais compacto
• Caption não é exibido
• Ideal para listas densas

Medium (padrão)

• Tamanho padrão
• Caption é exibido quando fornecido
• Melhor legibilidade

Ícones

O componente suporta ícones em duas posições:

🚀 Abrir no Storybook

Leading Icon

• Ícone à esquerda do conteúdo
• Usado para categorização ou identificação

Action Icon

• Ícone à direita
• Geralmente indica ação (seta, mais informações, etc.)

Tags

Tags podem ser adicionadas para destacar informações importantes:

🚀 Abrir no Storybook

Variantes de tag

O CardListItem aceita tanto string quanto TagProps no campo tag. A variante highlight é usada para chamar a atenção a itens críticos (type="important") ou neutros (type="neutral"), enquanto os tipos padrão (positive, neutral, default, negative, neutral-02, neutral-03) oferecem combinações com e sem ícone.

🚀 Abrir no Storybook

\n\n

Estados

O componente possui diferentes estados visuais:

🚀 Abrir no Storybook

Normal

Estado padrão, totalmente funcional

Disabled

Visualmente desabilitado, onClick não funciona

Loading

Exibe skeleton loader, ignora conteúdo

Largura

O componente pode ocupar toda a largura disponível:

🚀 Abrir no Storybook

Interatividade

Items podem ser clicáveis e responsivos:

🚀 Abrir no Storybook

API

Props

Prop	Tipo	Padrão	Descrição
title	string	-	O título do item (obrigatório)
description	string	-	A descrição opcional do item
caption	string	-	Texto de legenda (visível apenas no tamanho medium)
leadingIcon	ReactNode	-	Ícone exibido à esquerda do conteúdo
actionIcon	ReactNode	-	Ícone de ação exibido à direita
size	'small' | 'medium'	'medium'	O tamanho do componente
disabled	boolean	false	Desabilita o componente
fullWidth	boolean	false	Faz o componente ocupar toda a largura disponível
tag	string	-	Texto da tag exibida na área de tags
loading	boolean	false	Exibe estado de carregamento (skeleton)
onClick	() => void	-	Função chamada quando o item é clicado

Comportamento das props

• title: Sempre visível, único campo obrigatório
• description: Texto secundário opcional
• caption: Só aparece no tamanho medium
• loading: Quando true, substitui todo o conteúdo por skeleton
• disabled: Previne cliques e aplica estilo desabilitado
• tag: Exibida como destaque na área de tags

Classes CSS

Classe	Descrição
.ods-card-list-item	Estilos aplicados ao elemento raiz
.ods-card-list-item--size-small	Estilos aplicados quando size é small
.ods-card-list-item--size-medium	Estilos aplicados quando size é medium
.ods-card-list-item--disabled	Estilos aplicados quando disabled é true
.ods-card-list-item--full-width	Estilos aplicados quando fullWidth é true
.ods-card-list-item--loading	Estilos aplicados no estado de loading
.ods-card-list-item__leading-icon	Estilos aplicados ao ícone leading
.ods-card-list-item__content	Estilos aplicados ao container de conteúdo
.ods-card-list-item__content__title	Estilos aplicados ao título
.ods-card-list-item__content__description	Estilos aplicados à descrição
.ods-card-list-item__content__caption	Estilos aplicados à caption
.ods-card-list-item__action-icon	Estilos aplicados ao ícone de ação

Casos de uso comuns

Lista de produtos

<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
  <CardListItem
    title="iPhone 15 Pro"
    description="256GB, Titanium Natural"
    caption="Em estoque"
    tag="Novo"
  />
  <CardListItem
    title="MacBook Air M2"
    description="13 polegadas, 8GB RAM, 256GB SSD"
    caption="2 disponíveis"
  />
</div>

Lista de configurações

<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
  <CardListItem
    title="Notificações"
    description="Gerenciar alertas e notificações"
    size="small"
  />
  <CardListItem
    title="Privacidade"
    description="Controlar dados e privacidade"
    size="small"
  />
  <CardListItem
    title="Conta"
    description="Informações da conta e perfil"
    size="small"
  />
</div>

Lista de contatos

<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
  <CardListItem
    title="João Silva"
    description="joao.silva@email.com"
    caption="Online agora"
    tag="Admin"
  />
  <CardListItem
    title="Maria Santos"
    description="maria.santos@email.com"
    caption="Última atividade: 2h"
  />
</div>

Lista com carregamento

<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
  <CardListItem
    title="Item carregado"
    description="Este item já foi carregado"
  />
  <CardListItem
    title="Será ignorado"
    description="Conteúdo será substituído por skeleton"
    loading
  />
  <CardListItem
    title="Outro item carregado"
    description="Este também já foi carregado"
  />
</div>

Acessibilidade

• ✅ Estrutura semântica apropriada
• ✅ Navegação por teclado funcional
• ✅ Estados visuais claros (disabled, loading)
• ✅ Suporte a screen readers
• ✅ Contraste adequado em todos os estados

Navegação por teclado

Tecla	Função
Tab	Move o foco para o item (se clicável)
Enter/Space	Ativa o onClick do item

Melhores práticas

✅ Faça

• Use títulos descritivos e concisos
• Mantenha descrições informativas mas breves
• Use ícones que sejam facilmente reconhecíveis
• Use tags para destacar informações importantes
• Teste a funcionalidade de onClick quando usar
• Use tamanho small para listas densas
• Use tamanho medium quando precisar de mais informação

❌ Não faça

• Não use títulos muito longos que quebrem o layout
• Não omita descrições quando o contexto não for óbvio
• Não use muitas tags na mesma lista
• Não esqueça de testar o estado disabled
• Não ignore o estado de loading em listas dinâmicas
• Não use caption em itens small (não será exibido)

Links relacionados

• Tag - Para elementos de destaque
• Button - Para ações isoladas
• CardGroup - Para agrupamento de cards
• Storybook - CardListItem - Documentação técnica