CSS Parts

CSS Parts são pontos de customização visual expostos por componentes com Shadow DOM. Eles permitem aplicar estilos em partes internas específicas usando o seletor ::part(), sem quebrar o encapsulamento do componente.

Essa é a forma recomendada para pequenos ajustes visuais quando o componente documenta uma parte pública.

Componentes compostos e exportparts

Quando um componente com Shadow DOM contém outro Web Component, ::part() não atravessa o Shadow DOM automaticamente. O componente pai só deve expor uma parte interna do filho quando essa parte fizer parte do contrato visual público. Nesse caso, o filho declara part e o pai encaminha o nome com exportparts.

Exemplo conceitual:

<br-pagination variant="contextual"></br-pagination>

No host, a customização é feita com ::part():

br-pagination::part(per-page-input) {
  min-width: 6rem;
}

O br-pagination encaminha as partes públicas de br-select, br-button e do dropdown de reticências com nomes estáveis (per-page-*, go-to-*, prev-button-inner, next-button-inner e ellipsis-button). br-select, br-datetime-picker, br-menu-item e br-menu-list seguem o mesmo padrão quando compõem controles com partes públicas.

Nem todo filho interno deve ser encaminhado: ícones, elementos auxiliares e classes de implementação continuam encapsulados. A ausência de exportparts é intencional quando o filho não possui uma parte documentada para consumo externo.

Quando usar

Use CSS Parts quando você precisa ajustar uma parte interna documentada, por exemplo:

• A área interna de um botão.
• O conteúdo de um card, tooltip ou sign-in.
• Uma célula ou área de conteúdo de tabela.
• Um ícone ou container exposto pelo componente.

Se a personalização for sobre estado, densidade, ênfase ou variação suportada, prefira propriedades do componente. Use ::part() apenas quando a customização visual não estiver coberta por propriedades.

Sintaxe

br-button::part(button) {
  min-width: 12rem;
}

O trecho acima estiliza a parte chamada button exposta por br-button.

O nome usado dentro de ::part() precisa existir na documentação do componente. Se o componente não expõe a parte, o seletor não terá efeito.

Exemplo com botão

<br-button class="acao-principal" emphasis="primary"> Continuar </br-button>

.acao-principal::part(button) {
  justify-content: center;
  min-width: 14rem;
}

Esse ajuste altera apenas a parte interna exposta como button, mantendo o comportamento e a acessibilidade do componente.

Exemplo com sign-in

<br-sign-in class="entrada-govbr" 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
</br-sign-in>

.entrada-govbr::part(content) {
  font-weight: 700;
}

Nesse caso, a parte content controla a área de texto do br-sign-in.

Exemplo com tabela

<br-table class="tabela-servicos">
  <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>

.tabela-servicos::part(container) {
  border: 1px solid var(--gray-20);
}

br-table-cell::part(content) {
  white-space: nowrap;
}

O primeiro seletor ajusta o container exposto por br-table. O segundo ajusta a área de conteúdo das células.

Limitações

::part() só alcança partes expostas diretamente pelo componente selecionado. Ele não atravessa várias camadas de componentes sem que cada componente encaminhe explicitamente a parte com exportparts.

/* Funciona se br-table expuser a parte container */
br-table::part(container) {
  border-radius: 4px;
}

/* Não use ::part() para tentar alcançar uma estrutura interna não documentada */
br-table::part(container) .br-table-content {
  padding: 1rem;
}

Para customizar componentes filhos, aplique uma classe ou seletor diretamente no componente filho.

.tabela-servicos br-table-cell::part(content) {
  font-weight: 600;
}

Boas práticas

• Consulte a seção CSS Parts da página de cada componente antes de escrever o seletor.
• Prefira propriedades públicas para variações já previstas pelo componente.
• Evite depender de classes internas do Shadow DOM; elas não fazem parte do contrato público.
• Use classes na instância do componente para limitar o escopo da customização.
• Mantenha ajustes visuais pequenos. Se a mudança alterar comportamento ou estrutura, avalie criar uma variação no componente.

Relação com tokens

Quando possível, combine CSS Parts com tokens ou variáveis do GovBR-DS. Isso mantém a customização alinhada ao tema e reduz divergências visuais.

.entrada-govbr::part(content) {
  color: var(--color-primary-default);
}