Modal

O componente Modal é uma janela sobreposta que aparece sobre o conteúdo principal da aplicação. É ideal para exibir conteúdo importante que requer atenção imediata do usuário, como confirmações, formulários, ou informações detalhadas sem sair do contexto atual.

Importação

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

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

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

Importação de tipos TypeScript

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

// Uso em componente customizado
const MyModal: React.FC<{ isVisible: boolean }> = ({ isVisible }) => {
  const [open, setOpen] = React.useState(isVisible);

  return (
    <Modal
      isOpen={open}
      onRequestClose={() => setOpen(false)}
      contentLabel="Meu Modal"
      maxWidth="md"
    >
      <div>Conteúdo do modal</div>
    </Modal>
  );
};

Playground Interativo

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

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

function BasicModal() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Abrir Modal</button>
      <Modal
        isOpen={open}
        onRequestClose={() => setOpen(false)}
        contentLabel="Modal básico"
      >
        <div>
          <h2>Título do Modal</h2>
          <p>Conteúdo do modal aqui.</p>
          <button onClick={() => setOpen(false)}>Fechar</button>
        </div>
      </Modal>
    </>
  );
}

Tamanhos

O Modal oferece quatro tamanhos predefinidos para adequar-se ao conteúdo:

Tamanho	Largura	Uso recomendado
`sm`	420px	Confirmações simples e alertas
`md`	540px	Formulários e conteúdo geral (padrão)
`lg`	660px	Conteúdo extenso e formulários complexos
`xl`	780px	Conteúdo muito extenso e tabelas

🚀 Abrir no Storybook

Modal que se estende até a largura máxima disponível:

🚀 Abrir no Storybook

Para casos onde você quer controlar o fechamento apenas por ações específicas:

🚀 Abrir no Storybook

Responsividade

O Modal é automaticamente responsivo e se adapta a diferentes tamanhos de tela:

Desktop: Aparece centralizado com bordas arredondadas
Mobile: Aparece como bottom sheet com bordas arredondadas apenas no topo
Altura máxima: 80% da tela em dispositivos móveis
Transições: Animações suaves de abertura e fechamento

API

Props

Prop	Tipo	Padrão	Descrição
`children`	`ReactNode`	-	Conteúdo a ser exibido dentro do modal
`isOpen`	`boolean`	-	Controla se o modal está aberto
`onRequestClose`	`(event: MouseEvent \| KeyboardEvent) => void`	-	Função chamada quando o modal é solicitado para fechar
`blocked`	`boolean`	`false`	Se true, o modal se estende até a largura máxima
`maxWidth`	`'sm' \| 'md' \| 'lg' \| 'xl' \| false`	`false`	Determina a largura máxima do modal
`disableClose`	`boolean`	`false`	Desabilita o botão de fechar
`contentLabel`	`string`	-	Label para acessibilidade do conteúdo do modal
`ariaHideApp`	`boolean`	`true`	Controla se deve esconder a aplicação do screen reader
`closeTimeoutMS`	`number`	`150`	Tempo de animação para fechar o modal em milissegundos

Eventos

onRequestClose: Disparado quando o usuário tenta fechar o modal (Escape, clique no overlay, botão fechar)

Classes CSS

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

Classe	Descrição
`.ods-modal`	Container portal do modal
`.ods-modal__overlay`	Overlay de fundo do modal
`.ods-modal__overlay--after-open`	Modificador para overlay após abertura
`.ods-modal__overlay--before-close`	Modificador para overlay antes do fechamento
`.ods-modal__content`	Container principal do conteúdo do modal
`.ods-modal__content--after-open`	Modificador para conteúdo após abertura
`.ods-modal__content--before-close`	Modificador para conteúdo antes do fechamento
`.ods-modal__content--sm`	Modificador para modal de tamanho pequeno
`.ods-modal__content--md`	Modificador para modal de tamanho médio
`.ods-modal__content--lg`	Modificador para modal de tamanho grande
`.ods-modal__content--xl`	Modificador para modal de tamanho extra grande
`.ods-modal__content--blocked`	Modificador para modal bloqueado
`.ods-modal__header`	Cabeçalho do modal
`.ods-modal__header-close`	Botão de fechar do modal
`.ods-modal__body`	Corpo do modal onde fica o conteúdo

Acessibilidade

✅ Suporte completo a navegação por teclado
✅ Foco automático no modal quando aberto
✅ Escape para fechar o modal
✅ Overlay clicável para fechar
✅ Atributos ARIA apropriados
✅ Gestão de foco para screen readers
✅ Suporte ao contentLabel para identificação

Navegação por teclado

Tecla	Função
`Escape`	Fecha o modal
`Tab`	Navega pelos elementos

Melhores práticas

✅ Faça

Use para conteúdo importante que precisa de atenção imediata
Implemente fechamento via Escape e overlay
Forneça um contentLabel descritivo
Use tamanho apropriado para o conteúdo
Mantenha o foco dentro do modal quando aberto

❌ Não faça

Não use para navegação principal
Não omita formas de fechar o modal
Não coloque múltiplos modais abertos simultaneamente
Não use modal muito pequeno para conteúdo extenso
Não esqueça de gerenciar o foco adequadamente

Casos de uso comuns

function ConfirmationModal() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Deletar Item</button>
      <Modal
        isOpen={open}
        onRequestClose={() => setOpen(false)}
        contentLabel="Confirmar exclusão"
        maxWidth="sm"
      >
        <div style={{ padding: '24px', textAlign: 'center' }}>
          <h2>Confirmar Exclusão</h2>
          <p>
            Tem certeza que deseja deletar este item? Esta ação não pode ser
            desfeita.
          </p>
          <div
            style={{ display: 'flex', gap: '12px', justifyContent: 'center' }}
          >
            <button onClick={() => setOpen(false)}>Cancelar</button>
            <button
              onClick={() => setOpen(false)}
              style={{ background: 'red', color: 'white' }}
            >
              Deletar
            </button>
          </div>
        </div>
      </Modal>
    </>
  );
}

function FormModal() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Novo Produto</button>
      <Modal
        isOpen={open}
        onRequestClose={() => setOpen(false)}
        contentLabel="Criar produto"
        maxWidth="md"
      >
        <div style={{ padding: '24px' }}>
          <h2>Novo Produto</h2>
          <form>
            <div>
              <label>Nome do produto</label>
              <input type="text" />
            </div>
            <div>
              <label>Descrição</label>
            </div>
            <div>
              <label>Preço</label>
              <input type="number" />
            </div>
            <div>
              <button type="button" onClick={() => setOpen(false)}>
                Cancelar
              </button>
              <button type="submit">Salvar</button>
            </div>
          </form>
        </div>
      </Modal>
    </>
  );
}

function DetailsModal({ item }) {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Ver Detalhes</button>
      <Modal
        isOpen={open}
        onRequestClose={() => setOpen(false)}
        contentLabel="Detalhes do item"
        maxWidth="lg"
      >
        <div>
          <h2>{item.name}</h2>
          <div>
            <div>
              <h3>Informações Básicas</h3>
              <p>Código: {item.code}</p>
              <p>Categoria: {item.category}</p>
              <p>Status: {item.status}</p>
            </div>
            <div>
              <h3>Descrição</h3>
              <p>{item.description}</p>
            </div>
          </div>
          <button onClick={() => setOpen(false)}>Fechar</button>
        </div>
      </Modal>
    </>
  );
}

Links relacionados

Drawer - Para conteúdo lateral que não bloqueia a interação
ContextualMenu - Para menus de opções contextuais
Alert - Para notificações simples inline
Snackbar - Para feedback temporário
Storybook - Modal - Documentação técnica

Importação​

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

Importação de tipos TypeScript​

Playground Interativo​

Documentação Completa​

Uso básico​

Tamanhos​

Modal em bloco​

Modal sem botão fechar​

Responsividade​

API​

Props​

Eventos​

Classes CSS​

Acessibilidade​

Navegação por teclado​

Melhores práticas​

✅ Faça​

❌ Não faça​

Casos de uso comuns​

Modal de confirmação​

Modal de formulário​

Modal de detalhes​

Links relacionados​

Importação

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

Importação de tipos TypeScript

Playground Interativo

Documentação Completa

Uso básico

Tamanhos

Modal em bloco

Modal sem botão fechar

Responsividade

API

Props

Eventos

Classes CSS

Acessibilidade

Navegação por teclado

Melhores práticas

✅ Faça

❌ Não faça

Casos de uso comuns

Modal de confirmação

Modal de formulário

Modal de detalhes

Links relacionados