Badge

A badge shows one thing at a glance: a state, a value, a count. It is what powers the badges at the top of a dashboard, like the entity badge and the energy total badges. It is a compact pill with an optional icon, an optional label, and the value.

Use a badge for:

• A single fact, like a temperature, the state of a light, or a count
• A compact shortcut to more detail, like opening the more info dialog of an entity

Don't use a badge for:

• More than one fact. Use a card.
• A message that needs to be read, like an error. Use an alert.
• An action that is not about the value it shows. Use a button.

1. Container: the pill, with the background, border, and shadow of a card
2. Icon: optional, colored with the badge color. An image here becomes a round picture.
3. Label: optional small secondary text above the content
4. Content: the value or state

The label sits above the content, in small secondary text. Use it to say what the value is about, like the area or the entity name. Leave it out when the icon and value already make that clear.

By default, a badge is static. Make it a button badge when selecting it does something, like opening the more info dialog of an entity. A button badge gets hover and press feedback, a pointer cursor, and keyboard focus, and screen readers announce it as a button.

An icon only badge drops the label and content, and becomes a round icon. Use it only for icons people recognize without text. Otherwise, keep the text.

• Static: a badge of the default type has no hover, focus, or pressed state.
• Hover: a button badge gets an overlay in the badge color at 4% opacity.
• Pressed: a button badge gets an overlay in the badge color at 12% opacity.
• Focus: a focused button badge gets a border and a 1px ring in the badge color. The change takes 180ms.

• Keep a badge to a single fact. If you need more room, use a card.
• Only make a badge a button badge when selecting it does something. Don't make a badge look selectable when it isn't.
• See UI text for how to write states and units.

The badge has no key handler of its own. What Enter or Space do on a button badge depends on the handler the page adds.

A focused button badge gets a border and a thin ring in the badge color, only when you use a keyboard.

The badge is 36px high, and at least 36px wide.

A screen reader reads the label and the content. A button badge is announced as a button. An icon only badge has no text of its own, so it needs a name from the page that uses it.

• A button badge has the role button and tabindex="0". A static badge has no role, and can't be focused.
• The focus style uses :focus-visible.

• Label badge: the older round badge
• State icon: the icon that badges for entities show
• Alert: for a message instead of a value

The element is <ha-badge>. The content goes in the default slot, the icon in the icon slot.

<ha-badge label="Living room">
  <ha-svg-icon slot="icon" path="..."></ha-svg-icon>
  21.5 °C
</ha-badge>

<ha-badge type="button">On</ha-badge>

• type: badge (default) or button.
• label: small text above the content.
• icon-only: shows only the icon. Hides the label and the content.

• Default: the content of the badge.
• icon: the icon, usually an ha-svg-icon or ha-state-icon. An img in this slot is shown as a round 30 pixel picture, like an entity picture.

• --badge-color: the icon color, and the focus ring color. Defaults to var(--secondary-text-color). Dashboard badges set it to the state color of the entity.
• --ha-badge-size: the height, and the minimum width. Defaults to 36px.
• --ha-badge-border-radius: the corner radius. Defaults to half the size, which makes it a pill.
• --ha-badge-font-size: the size of the content text. Defaults to var(--ha-font-size-s).
• --ha-badge-icon-size: the icon size. Defaults to 18px.

The background, border, and shadow follow the card variables (--ha-card-background, --ha-card-border-color, --ha-card-border-width, --ha-card-box-shadow), so badges match the cards of the theme.

Source: src/components/ha-badge.ts