Skip to content

Polygon

A polygon adds a triangle, hexagon, or another many-sided shape anywhere on the card. Use it as a background, border, status surface, or as the matching background for a polygon-shaped horseshoe.

Basic configuration

Add polygons under layout.polygons. Choose the number of sides, width, and height:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
layout:
  polygons:
    - id: status-background
      xpos: 50
      ypos: 50
      sides: 6
      width: 80
      height: 55
      radius: 4
      styles:
        fill: var(--primary-color)
        fill-opacity: 0.2
        stroke: var(--primary-color)
        stroke-width: 1

An odd-sided polygon points upward by default. An even-sided polygon has a horizontal side at the top.

Choose the size and corners

width and height set the outside dimensions. Use equal values for an evenly proportioned polygon, or different values when the shape must fit a wider or taller area:

1
2
3
4
5
6
7
layout:
  polygons:
    - xpos: 50
      ypos: 50
      sides: 5
      width: 80
      height: 80

Add radius to round the corners. Its meaning is the same as for a rectangle; omit it for sharp corners.

Choose what faces upward

Corner numbers increase clockwise. A decimal identifies a point along the side leading to the next corner:

Triangle              Hexagon

    0                  0 --- 1
   / \                /       \
  2---1              5         2
                      \       /
                       4 --- 3

top places one of these positions at the top of the shape:

Value Result
top: 0 Corner 0 faces upward.
top: 0.5 The middle of the side from 0 to 1 faces upward.
top: 0.1 The point ten percent along the side from 0 to 1 faces upward.

This example turns a hexagon until corner 0 is at the top:

1
2
3
4
5
6
7
8
layout:
  polygons:
    - xpos: 50
      ypos: 50
      sides: 6
      width: 80
      height: 55
      top: 0

Match a polygon horseshoe

A polygon and a polygon-shaped horseshoe match exactly when their position, size, number of sides, and top value are equal. This lets you place a filled surface behind a gauge:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
layout:
  polygons:
    - xpos: 50
      ypos: 50
      sides: 6
      width: 80
      height: 55
      radius: 4
      top: 0.5
      styles:
        fill: var(--primary-color)
        fill-opacity: 0.12

  horseshoes:
    - entity_index: 0
      xpos: 50
      ypos: 50
      path:
        type: polygon
        sides: 6
        width: 80
        height: 55
        radius: 4
        top: 0.5
      horseshoe_scale:
        min: 0
        max: 100

See Horseshoe path shapes for partial polygon gauges and direction settings.

Configuration options

Field Required Default Description
xpos Yes Horizontal center position.
ypos Yes Vertical center position.
sides Yes Number of sides; use an integer of 3 or greater.
width Yes Exact outer width.
height Yes Exact outer height.
radius No 0 Corner radius; use 0 for sharp corners.
top No 0 for odd sides; 0.5 for even sides Side position that faces upward.
fill_mask No auto Fill width removed along the inside of the outline.
entity_index No Not set Entity used for value-dependent colors, actions, and animations.
styles No Default polygon style Fill, outline, opacity, and other SVG styles.
color_stops No Not set Colors the polygon from its entity value.

Styling and interaction

Polygons support the same fill and outline styles as rectangles. When both are translucent, fill_mask: auto prevents their colors from becoming darker where they meet.

Connect a polygon through entity_index when its color or behavior should follow an entity. Continue with Color stops, Color filters, Actions, and Animations.

The complete polygon and horseshoe example combines a filled polygon, a matching gauge, a state, and a slider.