Circle¶

A Circle is a round visual shape that can be placed anywhere on a card. It can be used as a background, ring, dot, badge, highlight, or another decorative/structural element around other content.

This page shows how to place and size a Circle, choose its fill and border, understand the preferred and legacy radius forms, and optionally let its color follow an entity value.

Add a Circle¶

Use a Circle for a round marker, background, border, status indicator, or decorative element.

1
2
3
4
5
6
7
8

layout:
  circles:
    - xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card
      radius_percent: 20  # Radius on the normal card coordinate scale
      styles:
        fill: var(--card-background-color)  # Fill color of this item
        stroke: var(--divider-color)  # Border color

Choose the size¶

For new configurations, prefer radius_percent. Despite its historical name, it follows the normal card coordinate scale, so the size is easy to relate to the rest of the layout:

1
2
3
4
5

layout:
  circles:
    - xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card
      radius_percent: 20  # Radius on the normal card coordinate scale

Older cards can use legacy radius, which is kept for compatibility and uses the older Circle sizing scale:

1
2
3
4
5

layout:
  circles:
    - xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card
      radius: 40  # Legacy radius; 40 gives the same size as radius_percent: 20

Use one radius method, not both. If both are present, radius_percent takes precedence.

Fill the Circle or show only the border¶

A Circle can use a fill, a border, or both, depending on whether it should look like a solid surface or a ring.

1
2
3
4
5
6
7
8
9

layout:
  circles:
    - xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card
      radius_percent: 20  # Radius on the normal card coordinate scale
      styles:
        fill: none  # Keep the inside transparent; draw only the border
        stroke: var(--primary-color)  # Border color
        stroke-width: 2  # Border thickness

Change color with an entity¶

Add entity_index, color_stops, and the matching item_style when the Circle color should follow a value or state. See Color stops.

Configuration options¶

A Circle always needs a position and a visible radius. Choose one radius method; do not configure both. radius_percent is the preferred current form. radius remains available for existing cards and uses the older sizing scale.

Position the Circle¶

Size the Circle with radius_percent¶

Use this method for new configurations.

Size the Circle with legacy radius¶

Use this only when maintaining existing YAML that already uses radius.

Options for every Circle¶

Related¶

• Shapes
• Appearance
• Color stops