Slots

Slots são pontos de entrada para conteúdo dentro de um Web Component. Eles permitem que você componha a interface com textos, ícones, imagens, links e outros elementos sem depender de uma propriedade específica para cada variação de conteúdo.

Na prática, o componente controla a estrutura, acessibilidade e comportamento. A aplicação fornece o conteúdo que entra nos espaços definidos pelo componente.

Quando usar

Use slots quando o conteúdo precisa ser flexível, sem alterar o contrato principal do componente.

Exemplos comuns:

• Texto ou ícone dentro de um botão.
• Mensagem de erro, sucesso ou ajuda dentro de um campo.
• Itens de navegação dentro de breadcrumb, menu, footer ou tabela.
• Conteúdo complementar, como imagem institucional em br-sign-in.

Slot padrão

O slot padrão recebe o conteúdo que não possui o atributo slot.

<br-button emphasis="primary"> Enviar solicitação </br-button>

Nesse exemplo, o texto Enviar solicitação entra no slot padrão do br-button.

Slots nomeados

Slots nomeados recebem conteúdo marcado com slot="nome-do-slot". Eles são usados quando o componente expõe mais de uma área de composição.

<br-input label="CPF" placeholder="000.000.000-00">
  <br-message slot="feedback" state="danger"> Informe um CPF válido. </br-message>
</br-input>

No exemplo acima, o br-message ocupa o slot feedback do br-input. Isso mantém a mensagem conectada visualmente ao campo, sem exigir que a aplicação conheça a estrutura interna do componente.

Compondo componentes

Slots também podem receber outros Web Components. Esse padrão é útil em componentes compostos, como tabela, menu, footer e breadcrumb.

<br-table>
  <br-table-header slot="header">
    <br-table-header-cell>Serviço</br-table-header-cell>
    <br-table-header-cell>Situação</br-table-header-cell>
  </br-table-header>

  <br-table-body slot="body">
    <br-table-row>
      <br-table-cell>Agendamento</br-table-cell>
      <br-table-cell>Disponível</br-table-cell>
    </br-table-row>
  </br-table-body>
</br-table>

O br-table recebe cabeçalho e corpo por slots nomeados. Cada parte continua sendo um componente independente, mas a tabela organiza o conjunto.

Conteúdo alternativo

Alguns componentes podem renderizar um conteúdo padrão quando o slot não é preenchido. Esse conteúdo é definido pelo próprio componente e deve ser tratado como comportamento interno.

<br-sign-in shape="circle" aria-label="Entrar com gov.br"> Entrar </br-sign-in>

Se você quiser substituir áreas opcionais, use os slots documentados pelo componente:

<br-sign-in shape="pill" aria-label="Entrar com conta gov.br">
  <br-icon
    slot="icon"
    svg='<svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8Zm0 2c-4.42 0-8 2.24-8 5v1h16v-1c0-2.76-3.58-5-8-5Z"/></svg>'
  ></br-icon>
  Entrar com gov.br
  <img slot="image" src="/img/logo-positive.svg" alt="GovBR-DS" />
</br-sign-in>

Boas práticas

• Consulte a seção Slots da página de cada componente para saber quais nomes estão disponíveis.
• Use o slot padrão para conteúdo principal e slots nomeados para áreas específicas.
• Evite inserir elementos interativos dentro de outro elemento interativo, como um botão dentro de br-button.
• Preserve nomes de slots exatamente como documentados, incluindo o caractere -.
• Em frameworks, defina o atributo slot no elemento filho que deve ser projetado.

Diferença entre slots e propriedades

Use propriedades para configurar comportamento e estado do componente.

Use slots para fornecer conteúdo.

<br-button emphasis="primary" density="small"> Salvar </br-button>

Nesse exemplo, emphasis e density configuram o componente. O texto Salvar é conteúdo projetado no slot padrão.