Button

O componente Button é usado para acionar uma ação ou evento, como submeter um formulário, abrir um diálogo, cancelar uma ação ou executar uma operação de delete.

Importação

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

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

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

Importação de tipos TypeScript

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

// Uso em componente customizado
const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

Playground Interativo

Explore o componente Button no playground interativo do Storybook:

🚀 Abrir no Storybook

Uso básico

<Button variant="primary">Botão primário</Button>

Variantes

O Button tem diferentes variantes para diferentes contextos de uso:

Primary

<Button variant="primary">Botão primário</Button>

Primary Critical

<Button variant="primaryCritical">Ação destrutiva principal</Button>

Secondary

<Button variant="secondary">Botão secundário</Button>

Secondary Critical

<Button variant="secondaryCritical">Ação destrutiva secundária</Button>

Tertiary

<Button variant="tertiary">Botão terciário</Button>

Tertiary Critical

<Button variant="tertiaryCritical">Ação destrutiva terciária</Button>

Text Tertiary

<Button variant="textTertiary">Texto terciário</Button>

Text Tertiary Critical

<Button variant="textTertiaryCritical">Texto destrutivo</Button>

Inverse

<div style={{ background: '#1a1a1a', padding: '16px', borderRadius: '8px' }}>
  <Button variant="inverse">Botão inverso</Button>
</div>

Guia de uso das variantes

• primary: Para ações principais e call-to-actions (máximo 1 por tela)
• primaryCritical: Para ações principais destrutivas (deletar, remover)
• secondary: Para ações secundárias e alternativas
• secondaryCritical: Para ações secundárias destrutivas
• tertiary: Para ações terciárias discretas
• tertiaryCritical: Para ações terciárias destrutivas
• textTertiary: Para ações discretas estilo link
• textTertiaryCritical: Para ações destrutivas discretas
• inverse: Para uso em fundos escuros

Tamanhos

Small

<Button size="sm" variant="primary">
  Pequeno
</Button>

Medium (padrão)

<Button size="md" variant="primary">
  Médio
</Button>

Large

<Button size="lg" variant="primary">
  Grande
</Button>

Estados

Disabled

<Button variant="primary" disabled>
  Botão desabilitado
</Button>

Loading

<Button variant="primary" loading>
  Carregando...
</Button>

Largura total

<Button variant="primary" blocked>
  Botão de largura total
</Button>

Tipos de botão

O componente Button suporta todos os tipos padrão de botão HTML. O atributo type determina o comportamento do botão em formulários.

Button (padrão)

<Button type="button" variant="primary">
  Ação personalizada
</Button>

Submit

<form
  onSubmit={(e) => {
    e.preventDefault();
    alert('Formulário enviado!');
  }}
>
  <input type="text" placeholder="Digite algo..." />
  <Button type="submit" variant="primary">
    Enviar
  </Button>
</form>

Reset

<form>
  <input
    type="text"
    defaultValue="Texto inicial"
    placeholder="Digite algo..."
  />
  <Button type="reset" variant="secondary">
    Limpar
  </Button>
</form>

Guia de tipos

Tipo	Descrição	Caso de Uso
button	Tipo padrão de botão	Ações gerais, interações JavaScript
submit	Envia dados do formulário	Envios de formulário, salvamento de dados
reset	Reseta campos do formulário	Funcionalidade de reset de formulário

API

Props

Prop	Tipo	Padrão	Descrição
variant	'primary' | 'primaryCritical' | 'secondary' | 'secondaryCritical' | 'tertiary' | 'tertiaryCritical' | 'textTertiary' | 'textTertiaryCritical' | 'inverse'	'primary'	Define o estilo visual do botão
size	'sm' | 'md' | 'lg'	'md'	Define o tamanho do botão
disabled	boolean	false	Desabilita o botão
loading	boolean	false	Mostra estado de carregamento
blocked	boolean	false	Faz o botão ocupar toda a largura disponível
iconLeft	string	-	Nome do ícone à esquerda do texto
iconRight	string	-	Nome do ícone à direita do texto
onClick	(event: MouseEvent) => void	-	Função chamada ao clicar no botão
type	'button' | 'submit' | 'reset'	'button'	Tipo do botão HTML
className	string	-	Classes CSS adicionais
children	ReactNode	-	Conteúdo do botão

Eventos

• onClick: Disparado quando o botão é clicado
• onFocus: Disparado quando o botão recebe foco
• onBlur: Disparado quando o botão perde foco

Acessibilidade

• ✅ Suporte completo a navegação por teclado
• ✅ Estados de foco visíveis
• ✅ Atributos ARIA apropriados
• ✅ Suporte a screen readers
• ✅ Contraste adequado em todos os estados
• ✅ Estados disabled adequadamente sinalizados
• ✅ Estados loading com feedback adequado
• ✅ Semântica HTML correta com tipos de botão apropriados

Considerações importantes

• Tipos semânticos: Use type="submit" para envios, type="button" para ações
• Estados disabled: Botões desabilitados não recebem foco e são anunciados corretamente
• Estados loading: O texto do botão muda para indicar o carregamento
• Contraste: Todas as variantes atendem aos padrões WCAG AA
• Textos descritivos: Use textos que indiquem claramente a ação a ser executada

Navegação por teclado

Tecla	Função
Tab	Move o foco para o botão
Space / Enter	Ativa o botão

CSS Classes

O componente Button utiliza as seguintes classes CSS que podem ser utilizadas para customizações:

Classe	Descrição
.ods-btn	Estilos aplicados ao elemento raiz
.ods-btn--primary	Define cor de fundo e texto primária do botão
.ods-btn--primary-critical	Define estilos do botão primary critical
.ods-btn--secondary	Define cor de fundo e texto secundária do botão
.ods-btn--secondary-critical	Define estilos do botão secondary critical
.ods-btn--tertiary	Define estilos do botão tertiary
.ods-btn--tertiary-critical	Define estilos do botão tertiary critical
.ods-btn--text-tertiary	Define estilos do botão text tertiary
.ods-btn--text-tertiary-critical	Define estilos do botão text tertiary critical
.ods-btn--inverse	Use o botão inverse em fundos escuros
.ods-btn--blocked	Faz o botão ocupar toda a largura do container pai

Melhores práticas

1. Envios de Formulário

✅ Faça

• Use type="submit" para o botão principal de envio do formulário
• Use type="button" para ações secundárias em formulários
• Use type="reset" com parcimônia e apenas quando o reset do formulário for necessário
• Combine loading com disabled durante envios para prevenir cliques duplos

❌ Não faça

• Não use múltiplos botões de submit no mesmo formulário
• Não omita validação antes de habilitar o botão de envio

2. Interações JavaScript

✅ Faça

• Use type="button" para botões que acionam funções JavaScript
• Forneça feedback visual claro para estados (loading, disabled)
• Use textos descritivos que indiquem claramente a ação

❌ Não faça

• Não use type="submit" para ações que não enviam formulários
• Isso previne envios acidentais de formulário

3. Performance e Responsividade

✅ Faça

• Use loading para operações assíncronas e prevenir cliques duplos
• Combine disabled com validação de formulário para melhor UX
• Use blocked em interfaces mobile para melhor usabilidade
• Implemente debounce em ações que podem ser acionadas rapidamente

❌ Não faça

• Não deixe botões sem feedback durante carregamentos
• Não use muitos botões primários na mesma tela
• Não ignore estados de carregamento em operações demoradas

Visão geral das variantes

Veja todas as variantes do Button em ação:

🚀 Abrir no Storybook

Links relacionados

• IconButton - Para botões apenas com ícone
• Link - Para navegação entre páginas
• ContextualMenu - Menu contextual acionado por botão
• Storybook - Button