Badge

Indicador de notificação sobreposto a um ícone, avatar ou botão, com contador numérico, modo ponto e cores semânticas.

O mk-badge sobrepõe um indicador de notificação ao conteúdo passado no slot default — tipicamente um ícone, avatar ou botão. Suporta contador numérico com limite máximo, modo dot (apenas um ponto), cores semânticas, posicionamento configurável e modo standalone (inline, sem overlay).

Padrão

Coloque o conteúdo âncora no slot e defina value com o número de notificações. A badge se posiciona no canto superior direito por padrão.

import { MkBadge, MkIcon } from '@db1/makuco-ui-react';

<MkBadge value={5}>
  <MkIcon name="bell" size="lg" />
</MkBadge>

<mk-badge [value]="5">
  <mk-icon name="bell" size="lg"></mk-icon>
</mk-badge>

Limite máximo

Quando value excede max, a badge exibe {max}+.

<MkBadge value={150} max={99}>
  <MkIcon name="bell" size="lg" />
</MkBadge>

<mk-badge [value]="150" [max]="99">
  <mk-icon name="bell" size="lg"></mk-icon>
</mk-badge>

Modo dot

Com dot, a badge mostra apenas um pequeno ponto, sem número.

<MkBadge dot>
  <MkIcon name="bell" size="lg" />
</MkBadge>

<mk-badge dot>
  <mk-icon name="bell" size="lg"></mk-icon>
</mk-badge>

Pulsante

Ative pulse para exibir um anel animado que se expande ao redor do indicador — um efeito "ping" para chamar a atenção do usuário (ex.: uma notificação urgente). Compõe com qualquer cor e com os modos número e dot. A animação respeita prefers-reduced-motion: quando o usuário pede movimento reduzido, o anel não anima.

<MkBadge value={5} pulse>
  <MkIcon name="bell" size="lg" />
</MkBadge>

<mk-badge [value]="5" pulse>
  <mk-icon name="bell" size="lg"></mk-icon>
</mk-badge>

Cores

Cinco cores semânticas: error (padrão), success, info, warning e brand.

<MkBadge value={3} color="success" standalone />
<MkBadge value={3} color="brand" standalone />

<mk-badge [value]="3" color="success" standalone></mk-badge>
<mk-badge [value]="3" color="brand" standalone></mk-badge>

Posicionamento

A prop placement define o canto sobre o qual a badge se posiciona.

<MkBadge value={5} placement="bottom-right">
  <MkIcon name="bell" size="lg" />
</MkBadge>

<mk-badge [value]="5" placement="bottom-right">
  <mk-icon name="bell" size="lg"></mk-icon>
</mk-badge>

Exibir zero

Por padrão a badge numérica fica oculta quando value é 0. Ative showZero para mantê-la visível.

<MkBadge value={0} showZero>
  <MkIcon name="bell" size="lg" />
</MkBadge>

<mk-badge [value]="0" show-zero>
  <mk-icon name="bell" size="lg"></mk-icon>
</mk-badge>

Standalone

Com standalone, a badge é renderizada inline, sem overlay — útil quando não há conteúdo no slot.

<MkBadge value={42} standalone />

<mk-badge [value]="42" standalone></mk-badge>

Props

Prop	Tipo	Padrão	Descrição
`value`	`number`	`0`	Valor numérico do contador exibido na badge.
`max`	`number`	`99`	Limite máximo do contador. Quando `value` excede `max`, exibe `{max}+`.
`dot`	`boolean`	`false`	Modo ponto — exibe apenas um pequeno indicador circular, sem número.
`showZero`	`boolean`	`false`	Exibe a badge mesmo quando `value` é `0`.
`color`	`"error" \| "success" \| "info" \| "warning" \| "brand"`	`"error"`	Cor semântica da badge.
`placement`	`"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"`	`"top-right"`	Posição da badge em relação ao conteúdo do slot.
`standalone`	`boolean`	`false`	Renderiza a badge inline (sem overlay absoluto).
`pulse`	`boolean`	`false`	Anima a badge com um anel pulsante ("ping") para chamar a atenção do usuário. Respeita `prefers-reduced-motion`.
`label`	`string`	—	Rótulo acessível opcional que substitui o texto gerado automaticamente (`"{n} notificações"`).

Slots

Slot	Descrição
(default)	Conteúdo âncora sobre o qual a badge se sobrepõe. Ignorado quando `standalone` está ativo.

Acessibilidade

A badge numérica usa role="status" e um aria-label descritivo (ex.: "5 notificações"). Quando value excede max, o rótulo vira mais de {max} notificações.
O aria-label automático pode ser sobrescrito pela prop label para contextos não relacionados a notificações.
No modo dot, a badge é decorativa: recebe aria-hidden="true" e não expõe role. O significado deve vir do conteúdo âncora.
O texto usa contraste branco sobre fundo semântico escuro, conforme WCAG 2.1 AA.

Badge

On this page