Text¶

The Text tool adds your own text to a card. It can show a heading, caption, unit, fixed label, or combine several pieces such as entity names and states into one positioned text item.

This page shows how to add plain and inline text, combine entity information, use multiple lines, style the text, and keep long labels readable.

Add text¶

Use Text for fixed wording or for a sentence assembled from literal text and entity information.

1
2
3
4
5

layout:
  texts:
    - text: Living room  # Text shown to the user
      xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 20  # Vertical position; 50 = center of the card

Style and position the text¶

Position and style Text when it needs to align with the surrounding card content instead of using its basic appearance.

1
2
3
4
5
6
7
8
9

layout:
  texts:
    - text: Living room  # Text shown to the user
      xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 20  # Vertical position; 50 = center of the card
      styles:
        font-size: 1.2em  # Size of the displayed text
        font-weight: bold  # Weight of the displayed text
        text-anchor: middle  # Horizontal alignment of the text

Combine text with entity information¶

Use inline text parts when one line should contain fixed text and entity information together. Each inline part can provide a fixed value or use supported name, state, or area information.

Keep the complete inline configuration inside the Text item so the order and spacing remain obvious.

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

entities:
  - entity: sensor.example_1  # Entity used by this example

layout:
  texts:
    - xpos: 50  # Horizontal position of the combined line
      ypos: 50  # Vertical position of the combined line
      text:
        - value: "Temperature: "  # Fixed text shown first
        - type: state  # Add the current entity state after the fixed text
          entity_index: 0  # Use the first configured entity for this part
          show:
            uom: end  # Show the entity unit after the state

Start a new line¶

Use new_line on an inline part when the next piece should continue on a new line. Use dx and dy to make small position adjustments between parts.

Keep long text readable¶

text_overflow.mode has three values:

• wrap — breaks text over multiple lines. Configure exactly one of characters or max_width; max_lines limits the number of lines and dy sets the spacing between generated lines.
• ellipsis — shortens text and adds .... Configure exactly one of characters or max_width.
• fit — reduces the text size until it fits within max_width. min_font_size sets the smallest allowed font size. Fit does not enlarge text, wrap it, or shorten it with ....

Wrap text¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

layout:  # Visible card items configured by this example
  texts:
    - text: A longer label that may need more than one line
      xpos: 50
      ypos: 30
      text_overflow:
        mode: wrap
        wrap:
          max_width: 40
          max_lines: 2
          dy: 1.2

Use characters instead of max_width when wrapping should be based on character count rather than measured width. Do not set both for the same wrap configuration.

Shorten text with an ellipsis¶

1
2
3
4
5
6
7
8
9

layout:  # Visible card items configured by this example
  texts:
    - text: A longer label that must stay on one line
      xpos: 50
      ypos: 50
      text_overflow:
        mode: ellipsis
        ellipsis:
          max_width: 40

Use characters instead of max_width when the limit should be a fixed character count. Do not set both for the same ellipsis configuration.

Shrink text to fit¶

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

layout:  # Visible card items configured by this example
  texts:
    - text: A complete label that must remain visible
      xpos: 50
      ypos: 70
      styles:
        font-size: 1.4em
      text_overflow:
        mode: fit
        fit:
          max_width: 40
          min_font_size: 0.8em

The configured font size is kept when the text already fits. When it is too wide, the card only reduces the size as far as needed, but not below min_font_size.

Configuration options¶

Choose plain text when one value is enough. Choose multipart text when several pieces — for example a label and an entity state — must be rendered together. In both cases the outer Text item still uses text:; localize_tag modifies a text value and does not replace the required text field.

Plain Text item¶

Multipart Text item¶

Here text is a list. Each list item is one visible part, in display order.

Literal inline part¶

Use this form for a fixed word, separator, unit, or other literal value inside multipart text.

Entity-derived inline part¶

Use this form when a part should show a Name, State, or Area instead of fixed text.

Options for every inline part¶

Options for every Text item¶

Related¶

• State
• Name
• Positioning and sizing