Rectangle¶

A rectangle adds a four-sided visual element anywhere on the card. Use it as a background, border, panel, highlight, or other visual element.

Rectangles can have a fixed size or automatically fit around a state, name, or area.

Basic configuration¶

Add rectangles under layout.rectangles:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

layout:
  rectangles:
    - id: background
      xpos: 50
      ypos: 50
      width: 40
      height: 12
      radius: 2
      styles:
        fill: var(--primary-color)
        opacity: 0.3

xpos and ypos position the center of the rectangle. width and height define its size.

radius rounds the corners.

For more about the card coordinate system, see Positioning and sizing.

Configuration options¶

Use either fixed xpos, ypos, width, and height, or fit.

Fit around another item¶

A rectangle can automatically follow the position and rendered size of a state, name, or area.

This is useful for backgrounds, borders, and highlights around text whose size can change because of formatting, fonts, values, or language.

The referenced item needs an id:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

layout:
  states:
    - id: current-state
      entity_index: 0
      xpos: 50
      ypos: 50

  rectangles:
    - id: state-background
      fit:
        section: states
        item_id: current-state
      radius: 2
      styles:
        fill: var(--primary-color)
        opacity: 0.3

Add extra space around the fitted item with padding:

1
2
3
4
5
6

fit:
  section: states
  item_id: current-state
  padding:
    x: 2
    y: 1

A fitted rectangle gets its position, width, and height from the referenced item, so fixed xpos, ypos, width, and height are not needed.

Fill and outline¶

Rectangles are SVG elements and can use standard SVG styling:

1
2
3
4
5

styles:
  fill: var(--card-background-color)
  stroke: var(--divider-color)
  stroke-width: 1
  opacity: 0.8

Common properties include:

When both the fill and outline are translucent, the colors would normally become darker where they overlap. The rectangle prevents that overlap automatically.

Set fill_mask to a number when you want to control how much fill is removed along the inside of the outline. A larger value reveals more of the card background between the fill and outline:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

layout:
  rectangles:
    - xpos: 50
      ypos: 50
      width: 40
      height: 20
      fill_mask: 2
      styles:
        fill: var(--primary-color)
        fill-opacity: 0.2
        stroke: var(--primary-color)
        stroke-width: 4
        stroke-opacity: 0.6

Keep fill_mask: auto when the fill should meet the inside of the outline without a deliberate gap.

See Styling for the complete styling guide.

Color from an entity¶

Connect a rectangle to an entity with entity_index when its color should respond to the entity state:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

layout:
  rectangles:
    - xpos: 50
      ypos: 50
      width: 40
      height: 12
      entity_index: 0

      show:
        item_style: colorstop

      colorstop:
        fill: true
        stroke: true

      styles:
        stroke-width: 1

      color_stops:
        colors:
          0: green
          50: orange
          100: red

Use colorstop for distinct color ranges or colorstopgradient for blended colors.

See Color stops for configuring ranges, gradients, palettes, and interpolation.

Related¶

• Circle
• Line
• Positioning and sizing
• Styling
• Color stops
• Actions
• Animations
• Reuse™