Visual Shapes: rectangles, lines, and circles¶

Visual shapes are simple SVG-based building blocks that help structure a card visually. They can be used as separators, backgrounds, highlights, indicators, or decorative elements.

The card supports four shape sections:

Shape	Section	Description
Rectangle	`rectangles`	A fixed rectangle or a rectangle that automatically fits another layout item
Circle	`circles`	A circle positioned by its center point, with either `radius` or `radius_percent`
Horizontal line	`hlines`	A horizontal line positioned by its center point and length
Vertical line	`vlines`	A vertical line positioned by its center point and length

All four shapes use the same 100x100 card coordinate system. This makes them easy to align with horseshoes, states, names, icons, and other layout items.

Basic usage¶

A rectangle can use a fixed center position, width, and height. It can also use fit to automatically follow the position and rendered size of a state, name, or area. A fitted rectangle adjusts when the content, number formatting, font, or language changes.

A circle needs a center position and a radius. The radius can be defined in pixels with radius, or as a percentage with radius_percent.

A horizontal or vertical line needs a center position and a length. The configuration is almost the same for both line types. The only difference is the section: horizontal lines are defined in hlines, while vertical lines are defined in vlines.

Shapes can also be connected to an entity by using entity_index. This allows color stops and animations to react to the state of that entity.

Example definitions¶

RectangleCircleHorizontal LineVertical Line

A fixed rectangle uses its own position and dimensions:

Fixed rectangle
- xpos: 50
  ypos: 50
  width: 40
  height: 12
  radius: 2
  styles:
    fill: var(--primary-color)
    opacity: 0.3

A fitted rectangle takes its position and dimensions from another layout item. The referenced item must have an id:

Rectangle fitted to a state
states:
  - id: current-state
    entity_index: 0
    xpos: 50
    ypos: 50

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

Basic Circle 1
- xpos: 50                  # xpos=50 is center position
  ypos: 50                  # ypos=50 is center position
  radius: 25                # radius (in pixels) of circle
  styles:
    stroke-width: 2         # Set stroke width using CSS attribute

Basic Circle 2
- xpos: 50                  # xpos=50 is center position
  ypos: 50                  # ypos=50 is center position
  radius_percent: 25        # radius (in %) of circle
  entity_index: 0           # connects to entity 0 in the entity definitions
  styles:
    stroke-width: 2         # Set stroke width using CSS attribute
  color_stops:               # Use of color stop: color of circle depends on state
    colors:
      0: 'blue'
      0.1: 'green'
      0.4: 'yellow'
      1: 'orange'
      3: 'red'
      5: 'purple'

Horizontal / Vertical config
- xpos: 50                  # xpos=50 is center position
  ypos: 50                  # ypos=50 is center position
  length: 25                # length of line.
  entity_index: 0           # connect to state of entity 0
  styles:
    stroke-width: 2         # Set stroke width using CSS attribute

Horizontal / Vertical config
- xpos: 50                  # xpos=50 is center position
  ypos: 50                  # ypos=50 is center position
  length: 25                # length of line.
  entity_index: 0           # connect to state of entity 0
  styles:
    stroke-width: 2         # Set stroke width using CSS attribute
  color_stops:               # Use of color stop: color of circle depends on state
    colors:
      0: 'blue'
      0.1: 'green'
      0.4: 'yellow'
      1: 'orange'
      3: 'red'
      5: 'purple'

Horizontal / Vertical config
- xpos: 50                  # xpos=50 is center position
  ypos: 50                  # ypos=50 is center position
  length: 25                # length of line.
  entity_index: 0           # connect to state of entity 0
  styles:
    stroke-width: 2         # Set stroke width using CSS attribute

Horizontal / Vertical config
- xpos: 50                  # xpos=50 is center position
  ypos: 50                  # ypos=50 is center position
  length: 25                # length of line.
  entity_index: 0           # connect to state of entity 0
  styles:
    stroke-width: 2         # Set stroke width using CSS attribute
  color_stops:               # Use of color stop: color of circle depends on state
    colors:
      0: 'blue'
      0.1: 'green'
      0.4: 'yellow'
      1: 'orange'
      3: 'red'
      5: 'purple'

Configuration fields¶

The required fields depend on the shape type. Rectangles use fixed dimensions or fit, circles use a radius, and lines use a length.

RectangleCircleHorizontal LineVertical Line

Field	Required	Default	Description
`xpos`	Fixed only		X position of the rectangle center
`ypos`	Fixed only		Y position of the rectangle center
`width`	Fixed only		Rectangle width
`height`	Fixed only		Rectangle height
`fit.section`	Fit only		Section containing the referenced item: `states`, `names`, or `areas`
`fit.item_id`	Fit only		`id` of the referenced item
`fit.padding.x`		`1.5`	Horizontal padding around the measured item
`fit.padding.y`		`0.5`	Vertical padding around the measured item
`radius`		`0`	Corner radius
`entity_index`		Not set	Index in the `entities` section
`styles`		`fill: var(--primary-background-color); stroke: none; stroke-width: 0`	CSS style definitions
`color_stops`		Not set	Color stops used to set the fill color based on the entity state

Note

Use either xpos, ypos, width, and height, or use fit. A fitted rectangle obtains all four geometry values from the referenced item.

Field	Required	Default	Description
`xpos`			X position on the 100x100 card canvas
`ypos`			Y position on the 100x100 card canvas
`radius`	One required	`0`	Circle radius in SVG units
`radius_percent`	One required	Not set	Circle radius using the card percentage scale
`entity_index`		Not set	Index in the `entities` section
`styles`		`{}`	CSS style definitions
`color_stops`		Not set	Color stops used to set the shape color based on the entity state

Note

Use either radius or radius_percent.

Field	Default	Description
`xpos`	`50`	X position on the 100x100 card canvas
`ypos`	`50`	Y position on the 100x100 card canvas
`length`	`10`	Length of the horizontal line
`entity_index`	Not set	Index in the `entities` section
`styles`	`stroke: var(--primary-text-color); stroke-width: 2; opacity: 1; stroke-linecap: round`	CSS style definitions
`color_stops`	Not set	Color stops used to set the line color based on the entity state

Field	Default	Description
`xpos`	`50`	X position on the 100x100 card canvas
`ypos`	`50`	Y position on the 100x100 card canvas
`length`	`10`	Length of the vertical line
`entity_index`	Not set	Index in the `entities` section
`styles`	`stroke: var(--primary-text-color); stroke-width: 2; opacity: 1; stroke-linecap: round`	CSS style definitions
`color_stops`	Not set	Color stops used to set the line color based on the entity state

Shared fields¶

These fields can be used with rectangles, circles, horizontal lines, and vertical lines.

Field	Default	Description
`id`	Not set	Optional unique id within the section, used by `same_as`
`group`	`card`	Group this visual shape belongs to
`same_as*`	Not set	Reuse another item from the same section. See the `same_as` documentation

Styling¶

Visual shapes are SVG elements, so they can be styled with CSS properties in the styles section.

Method	Support	Description
`styles`		Inline SVG and CSS styles

Popular style properties¶

RectangleCircleHorizontal LineVertical Line

Property	What it does	Example
`fill`	Sets the fill color	`fill: red`
`stroke`	Sets the outline color	`stroke: blue`
`stroke-width`	Sets the outline width	`stroke-width: 1em`
`opacity`	Sets the opacity of the complete rectangle	`opacity: 0.7`
`fill-opacity`	Sets the opacity of the fill	`fill-opacity: 0.5`
`stroke-opacity`	Sets the opacity of the outline	`stroke-opacity: 0.5`

Property	What it does	Example
`fill`	Sets the fill color	`fill: red`
`stroke`	Sets the outline color	`stroke: blue`
`stroke-width`	Sets the outline width	`stroke-width: 2em`
`opacity`	Sets the opacity of the full circle	`opacity: 0.7`
`fill-opacity`	Sets the opacity of the fill	`fill-opacity: 0.5`
`stroke-opacity`	Sets the opacity of the outline	`stroke-opacity: 0.5`

Property	What it does	Example
`stroke`	Sets the line color	`stroke: red`
`stroke-width`	Sets the line width	`stroke-width: 2em`
`opacity`	Sets the line opacity	`opacity: 0.7`
`stroke-linecap`	Sets the line ending	`round`, `butt`, or `square`

Property	What it does	Example
`stroke`	Sets the line color	`stroke: red`
`stroke-width`	Sets the line width	`stroke-width: 2em`
`opacity`	Sets the line opacity	`opacity: 0.7`
`stroke-linecap`	Sets the line ending	`round`, `butt`, or `square`

Color stops and animations¶

Visual shapes can use color stops and animations when they are connected to an entity.

Method	Support	Description
`color_stops`		List of state values used to set the shape color
`animations`		State-based animations using class or style changes

Info

Animations require the visual shape to be connected to an entity with entity_index.