ListAction

O componente ListAction é um item de lista interativo que combina conteúdo textual com ações do usuário. Ideal para listas de configurações, menus de opções, navegação entre telas e exibição de informações acionáveis.

Importação

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

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

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

Importação de tipos TypeScript

import type { ListActionProps, ActionItem } from '@useblu/ocean-react';

// Uso em componente customizado
const MyListAction: React.FC<ListActionProps> = (props) => {
  return <ListAction {...props} />;
};

Playground Interativo

Explore o componente ListAction no playground interativo do Storybook:

🚀 Abrir no Storybook

Uso básico

<ListAction
  title="Título do Item"
  description="Descrição ou informação adicional"
  onClick={() => alert('Item clicado!')}
/>

Tipos de borda

O ListAction oferece dois tipos de borda para diferentes contextos visuais:

Card (padrão)

Exibe o item com borda de card, ideal para itens individuais ou destacados:

<ListAction
  type="card"
  title="Item com borda de card"
  description="Estilo padrão com bordas arredondadas"
  onClick={() => alert('Clicado!')}
/>

Text

Exibe o item sem borda de card, ideal para listas longas:

<div>
  <ListAction
    type="text"
    title="Primeiro item"
    description="Sem borda de card"
    showDivider
    onClick={() => alert('Clicado!')}
  />
  <ListAction
    type="text"
    title="Segundo item"
    description="Com divisor entre itens"
    showDivider
    onClick={() => alert('Clicado!')}
  />
  <ListAction
    type="text"
    title="Último item"
    description="Sem divisor no último"
    onClick={() => alert('Clicado!')}
  />
</div>

Status de conteúdo

O ListAction oferece diferentes status visuais para destacar estados ou categorias de informação:

Default

<ListAction
  status="default"
  title="Configurações gerais"
  description="Gerencie suas preferências"
/>

Inactive

<ListAction
  status="inactive"
  title="Serviço indisponível"
  description="Este serviço está temporariamente desabilitado"
/>

Positive

<ListAction
  status="positive"
  title="Pagamento confirmado"
  description="R$ 150,00"
/>

Warning

<ListAction
  status="warning"
  title="Atenção necessária"
  description="Verifique suas informações"
/>

Highlight

<ListAction
  status="highlight"
  title="Novidade!"
  description="Conheça nossa nova funcionalidade"
/>

Highlight Lead

<ListAction
  status="highlight-lead"
  title="R$ 1.250,00"
  description="Valor destacado"
/>

Strikethrough

<ListAction
  status="strikethrough"
  title="Oferta expirada"
  strikethroughDescription="De R$ 299,00"
  description="Por R$ 199,00"
/>

Guia de uso dos status

• default: Status padrão para itens comuns de lista
• inactive: Para itens desabilitados ou indisponíveis
• positive: Para destacar informações positivas (sucesso, confirmação)
• warning: Para alertas ou itens que necessitam atenção
• highlight: Para destacar novidades ou itens importantes
• highlight-lead: Para destacar valores monetários ou métricas principais
• strikethrough: Para itens obsoletos ou descontinuados

Conteúdo invertido

O prop inverted inverte a posição do título e da descrição, útil para priorizar valores ou descrições:

<div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
  <ListAction title="Saldo disponível" description="R$ 1.250,00" />

  <ListAction inverted title="R$ 1.250,00" description="Saldo disponível" />
</div>

Descrição com tachado

Use strikethroughDescription junto com status="strikethrough" para mostrar valores antigos:

<ListAction
  status="strikethrough"
  title="Produto em promoção"
  strikethroughDescription="De R$ 299,00 "
  description="Por R$ 199,00"
/>

Caption (legenda)

Adicione uma terceira linha de texto com o prop caption:

<ListAction
  title="Transferência realizada"
  description="R$ 500,00"
  caption="Hoje às 14:32"
/>

Ícones

Adicione ícones à esquerda para melhor identificação visual:

<ListAction
  icon={<PlaceholderOutline size={24} />}
  title="Meus documentos"
  description="Acesse seus arquivos"
/>

Indicadores

Use indicadores (badges, tags) à direita do conteúdo antes da ação:

<div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
  <ListAction
    title="Notificações"
    description="Você tem novas mensagens"
    indicator={<Badge count={5} color="brand" />}
  />

  <ListAction
    title="Novo recurso"
    description="Experimente agora"
    indicator={
      <Tag type="positive" size="small">
        Novo
      </Tag>
    }
  />
</div>

Tipos de ação

O ListAction suporta três tipos de ação: chevron (padrão), menu e swipe.

Chevron (navegação)

Tipo padrão que indica navegação para outra tela:

<ListAction
  actionType="chevron"
  title="Minha conta"
  description="Gerenciar informações pessoais"
  onClick={() => alert('Navegar para Minha conta')}
/>

Menu (ações múltiplas)

Exibe um menu dropdown com múltiplas ações:

<ListAction
  actionType="menu"
  title="Documento importante"
  description="relatório-anual.pdf"
  menuActions={[
    {
      label: 'Editar',
      icon: <Pencil size={20} />,
      onClick: () => alert('Editar'),
    },
    {
      label: 'Compartilhar',
      icon: <Share size={20} />,
      onClick: () => alert('Compartilhar'),
    },
    {
      label: 'Arquivar',
      icon: <Archive size={20} />,
      onClick: () => alert('Arquivar'),
      variant: 'positive',
    },
    {
      label: 'Excluir',
      icon: <Trash size={20} />,
      onClick: () => alert('Excluir'),
      variant: 'negative',
    },
  ]}
/>

Swipe (ações rápidas)

Permite revelar ações deslizando o item (mobile-friendly):

<ListAction
  actionType="swipe"
  title="Email importante"
  description="Arraste para ver ações"
  menuActions={[
    {
      label: 'Editar',
      icon: <Pencil size={20} />,
      onClick: () => alert('Editar'),
    },
    {
      label: 'Excluir',
      icon: <Trash size={20} />,
      onClick: () => alert('Excluir'),
      variant: 'negative',
    },
  ]}
/>

Posicionamento do menu

Para o tipo menu, você pode controlar a posição do dropdown:

<div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
  <ListAction
    actionType="menu"
    menuPosition="bottom-right"
    title="Menu à direita (padrão)"
    description="Abrir dropdown"
    menuActions={[
      {
        label: 'Ação 1',
        onClick: () => alert('Ação 1'),
      },
    ]}
  />

  <ListAction
    actionType="menu"
    menuPosition="bottom-left"
    title="Menu à esquerda"
    description="Abrir dropdown"
    menuActions={[
      {
        label: 'Ação 1',
        onClick: () => alert('Ação 1'),
      },
    ]}
  />
</div>

Estados

Disabled

<ListAction
  title="Opção desabilitada"
  description="Esta opção não está disponível"
  disabled
/>

Loading

Mostra um skeleton placeholder durante carregamento:

<ListAction title="Carregando..." description="Aguarde" loading />

Exemplos práticos

Lista de configurações

<List>
  <ListAction
    icon={<PlaceholderOutline size={24} />}
    title="Perfil"
    description="Editar informações pessoais"
    onClick={() => alert('Abrir perfil')}
  />
  <ListAction
    icon={<PlaceholderOutline size={24} />}
    title="Notificações"
    description="Gerenciar alertas"
    indicator={<Badge count={3} color="brand" />}
    onClick={() => alert('Abrir notificações')}
  />
  <ListAction
    icon={<PlaceholderOutline size={24} />}
    title="Privacidade"
    description="Controlar dados e permissões"
    onClick={() => alert('Abrir privacidade')}
  />
  <ListAction
    icon={<PlaceholderOutline size={24} />}
    title="Ajuda e Suporte"
    description="Central de ajuda"
    onClick={() => alert('Abrir ajuda')}
  />
</List>

Lista de transações

<List>
  <ListAction
    status="positive"
    inverted
    title="+ R$ 1.500,00"
    description="Salário recebido"
    caption="Hoje às 09:00"
    actionType="menu"
    menuActions={[
      { label: 'Ver detalhes', onClick: () => {} },
      { label: 'Compartilhar', onClick: () => {} },
    ]}
  />
  <ListAction
    status="default"
    inverted
    title="- R$ 45,90"
    description="Supermercado"
    caption="Ontem às 18:30"
    actionType="menu"
    menuActions={[
      { label: 'Ver detalhes', onClick: () => {} },
      { label: 'Categorizar', onClick: () => {} },
    ]}
  />
  <ListAction
    status="warning"
    inverted
    title="- R$ 250,00"
    description="Fatura pendente"
    caption="Vence em 2 dias"
    indicator={
      <Tag type="warning" size="small">
        Pendente
      </Tag>
    }
    onClick={() => alert('Ver fatura')}
  />
</List>

Lista com tipo text e divisores

<div>
  <ListAction
    type="text"
    title="Card com tipo Text"
    description="R$ 1.234,56"
    caption="Legenda terciária"
    icon={<PlaceholderOutline size={24} />}
    showDivider
    onClick={() => alert('Clicado!')}
  />
  <ListAction
    type="text"
    title="Card com Caption"
    description="Descrição secundária"
    caption="12/12/2024 às 14:30"
    icon={<PlaceholderOutline size={24} />}
    showDivider
    onClick={() => alert('Clicado!')}
  />
  <ListAction
    type="text"
    title="Último Card sem Divisor"
    description="Sem showDivider"
    caption="Este é o último item"
    icon={<PlaceholderOutline size={24} />}
    onClick={() => alert('Clicado!')}
  />
</div>

API

Props

Prop	Tipo	Padrão	Descrição
title	string	-	Título principal do item (obrigatório)
description	string	-	Descrição ou texto secundário
strikethroughDescription	string	-	Descrição com texto riscado (valor antigo)
caption	string	-	Legenda ou texto terciário
inverted	boolean	false	Inverte posição do título com descrição
type	'card' | 'text'	'card'	Tipo de borda do item
status	'default' | 'inactive' | 'positive' | 'warning' | 'highlight' | 'highlight-lead' | 'strikethrough'	'default'	Status visual do conteúdo
showDivider	boolean	false	Mostra divisor entre itens (apenas para type="text")
highlight	{ caption: string | ReactNode; backgroundColor?: string; captionColor?: string }	-	Exibe área de destaque com texto ou conteúdo na base do card
disabled	boolean	false	Desabilita o item
loading	boolean	false	Exibe skeleton de carregamento
icon	ReactNode	-	Ícone exibido no início do item
indicator	ReactNode	-	Indicador (badge/tag) antes da ação
actionType	'chevron' | 'menu' | 'swipe'	'chevron'	Tipo de ação do item
menuActions	ActionItem[]	-	Lista de ações para tipos menu/swipe
menuPosition	'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'	'bottom-right'	Posição do menu dropdown
onClick	(event: React.MouseEvent<HTMLButtonElement>) => void	-	Função chamada ao clicar no item
className	string	-	Classes CSS adicionais

ActionItem (menuActions)

Prop	Tipo	Descrição
label	string	Texto da ação
icon	ReactNode	Ícone da ação
onClick	() => void	Função executada ao clicar na ação
variant	'default' | 'positive' | 'negative'	Variante visual da ação

Eventos

• onClick: Disparado quando o item é clicado (não aplicável para tipo swipe)
• Cada ActionItem tem seu próprio onClick independente

Acessibilidade

• ✅ Elemento <button> semântico para acessibilidade
• ✅ Suporte completo a navegação por teclado
• ✅ Estados de foco visíveis
• ✅ Estados disabled adequadamente sinalizados
• ✅ Skeleton acessível durante loading
• ✅ Menu dropdown acessível com navegação por teclado
• ✅ Ações de swipe com alternativa por teclado

Navegação por teclado

Tecla	Função
Tab	Move o foco para o item ou menu
Space / Enter	Ativa o item ou abre o menu
Escape	Fecha o menu dropdown (tipo menu)
↑ / ↓	Navega entre opções do menu (tipo menu)

Melhores práticas

✅ Faça

• Use títulos claros e descritivos que indiquem o conteúdo ou ação
• Combine com List para agrupar múltiplos itens relacionados
• Use o status apropriado para comunicar estados (positive, warning, etc.)
• Utilize indicadores (badges/tags) para informações de status
• Prefira actionType="chevron" para navegação simples
• Use actionType="menu" quando houver múltiplas ações disponíveis
• Use actionType="swipe" em interfaces mobile para economia de espaço
• Forneça feedback visual durante operações com loading
• Use inverted quando o valor/descrição for mais importante que o título
• Limite menuActions a 3-5 itens para melhor usabilidade
• Use type="text" com showDivider para listas longas sem bordas

❌ Não faça

• Não use textos muito longos que truncam em dispositivos pequenos
• Não omita o onClick quando o item for clicável
• Não use múltiplos indicadores no mesmo item (mantém o design limpo)
• Não misture tipos de ação inconsistentemente na mesma lista
• Não use status strikethrough sem contexto claro
• Não coloque ações críticas (delete) sem confirmação
• Não sobrecarregue o menu com muitas opções
• Não use disabled sem indicar o motivo ao usuário
• Não ignore estados de loading em operações assíncronas

Visão geral dos status

Veja todos os status de conteúdo do ListAction:

🚀 Abrir no Storybook

Visão geral dos tipos de ação

Veja todos os tipos de ação disponíveis:

🚀 Abrir no Storybook

Comparação Card vs Text

Veja a diferença entre os tipos card e text:

🚀 Abrir no Storybook

Documentação Completa

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

No Storybook você encontrará:

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

Links relacionados

• List - Container para agrupar itens
• Badge - Para indicadores numéricos
• Tag - Para indicadores de categoria/status
• TransactionListItem - Para transações financeiras
• SettingsListItem - Para itens de configuração
• Storybook - ListAction