kalkih/mini-graph-card

A minimalistic and customizable graph card for Home Assistant Lovelace UI.

The card works with entities from within the sensor & binary_sensor domain and displays the sensors current state as well as a line graph representation of the history.

This card is available in HACS (Home Assistant Community Store).

HACS is a third party community store and is not included in Home Assistant out of the box.

1. Download and copy mini-graph-card-bundle.js from the latest release into your config/www directory.

2. Add the resource reference as decribed below.

1. Move into your config/www directory.

2. Grab mini-graph-card-bundle.js:

$ wget https://github.com/kalkih/mini-graph-card/releases/download/v0.13.0/mini-graph-card-bundle.js

1. Add the resource reference as decribed below.

If you configure Lovelace via YAML, add a reference to mini-graph-card-bundle.js inside your configuration.yaml:

resources:
  - url: /local/mini-graph-card-bundle.js?v=0.13.0
    type: module

Else, if you prefer the graphical editor, use the menu to add the resource:

1. Make sure, advanced mode is enabled in your user profile (click on your user name to get there)
2. Navigate to Configuration -> Lovelace Dashboards -> Resources Tab. Hit orange (+) icon
3. Enter URL /local/mini-graph-card-bundle.js and select type "JavaScript Module". (Use /hacsfiles/mini-graph-card/mini-graph-card-bundle.js and select "JavaScript Module" for HACS install)
4. Restart Home Assistant.

If you have a version older than v0.0.8 installed, please delete the current files and follow the installation instructions again.

1. Find your mini-graph-card-bundle.js file in config/www or wherever you ended up storing it.

2. Replace the local file with the latest one attached in the latest release.

3. Add the new version number to the end of the cards reference url in your ui-lovelace.yaml like below:

resources:
  - url: /local/mini-graph-card-bundle.js?v=0.13.0
    type: module

You may need to empty the browsers cache if you have problems loading the updated card.

We recommend looking at the Example usage section to understand the basics to configure this card. (also) pay attention to the required options mentioned below.

Entities may be listed directly (as per sensor.temperature in the example below), or defined using properties of the Entity object detailed in the following table (as per sensor.pressure in the example below).

entities:
  - sensor.temperature
  - entity: sensor.pressure
    name: Pressure
    show_state: true
  - sensor.humidity

All properties are optional.

See dynamic line color for example usage.

As long as the first and last threshold stops have value properties, intermediate stops can exclude value; they will be interpolated linearly. For example, given stops like:

color_thresholds:
  - value: 0
    color: "#ff0000"
  - color: "#ffff00"
  - color: "#00ff00"
  - value: 4
    color: "#0000ff"

The values will be interpolated as:

color_thresholds:
  - value: 0
    color: "#ff0000"
  - value: 1.333333
    color: "#ffff00"
  - value: 2.666667
    color: "#00ff00"
  - value: 4
    color: "#0000ff"

The example above will result in the following colors of the graph: if value is

• between 0 (including this value) and 1.33333, the color is #ff0000,
• between 1.33333 (including this value) and 2.666667, the color is #ffff00,
• between 2.666667 (including this value) and 4, the color is #00ff00,
• equal to or more than 4, the color is #0000ff.

As a shorthand, you can just use a color string for the stops that you want interpolated:

  - value: 0
    color: "#ff0000"
  - "#ffff00"
  - "#00ff00"
  - value: 4
    color: "#0000ff"

Recorded values are grouped in time buckets which are determined by group_by, points_per_hour configuration. These buckets are converted later to single point/bar on the graph. Aggregate function defines the methods of that conversion.

The following theme variables can be set in your HA theme to customize the appearance of the card.

type: custom:mini-graph-card
entities:
 - sensor.illumination

type: custom:mini-graph-card
entities:
 - sensor.illumination
align_icon: left
align_state: center
show:
  fill: false

type: custom:mini-graph-card
name: SERVER
icon: mdi:server
entities:
  - entity: sensor.server_total
    name: TOTAL
  - sensor.server_sent
  - sensor.server_received

type: custom:mini-graph-card
entities:
  - entity: sensor.energy_consumption
name: ENERGY CONSUMPTION
show:
  graph: bar

Use the hours_to_show option to specify how many hours of history the graph should represent. Use the points_per_hour option to specify the accuracy/detail of the graph.

type: custom:mini-graph-card
entities:
  - sensor.living_room_temp
name: LIVING ROOM
hours_to_show: 168
points_per_hour: 0.25

Use the show option to show/hide UI elements.

type: custom:mini-graph-card
entities:
  - sensor.humidity
show:
  icon: false
  name: false
  state: false

You can stack cards horizontally by using one or more horizontal-stack(s).

type: horizontal-stack
cards:
  - type: custom:mini-graph-card
    entities:
      - sensor.humidity
    line_color: blue
    line_width: 8
    font_size: 75
  - type: custom:mini-graph-card
    entities:
      - sensor.illumination
    line_color: '#e74c3c'
    line_width: 8
    font_size: 75
  - type: custom:mini-graph-card
    entities:
      - sensor.temperature
    line_color: var(--accent-color)
    line_width: 8
    font_size: 75

Have the graph change line color dynamically.

type: custom:mini-graph-card
entities:
  - sensor.sensor_temperature
show:
  labels: true
color_thresholds:
  - value: 20
    color: "#f39c12"
  - value: 21
    color: "#d35400"
  - value: 21.5
    color: "#c0392b"

Have one or more series plot on a separate y-axis, which appears on the right side of the graph. This example also shows turning off the line, points and legend.

type: custom:mini-graph-card
entities:
  - entity: sensor.verandah
    name: Verandah
  - entity: sensor.lounge
    name: Lounge
  - entity: sensor.kitchen
    name: Kitchen
  - color: gray
    entity: input_number.nighttime
    name: Night
    show_line: false
    show_points: false
    show_legend: false
    y_axis: secondary
show:
  labels: true
  labels_secondary: true

You can group values by date, this way you can visualize for example daily energy consumption.

type: custom:mini-graph-card
entities:
  - entity: sensor.energy_daily
name: Energy consumption
hours_to_show: 168
aggregate_func: max
group_by: date
show:
  graph: bar

You can decide how values are aggregated for points on graph. Example how to display min, max, avg temperature per day from last week.

type: custom:mini-graph-card
entities:
  - entity: sensor.outside_temp
    aggregate_func: max
    name: Max
    color: "#e74c3c"
  - entity: sensor.outside_temp
    aggregate_func: min
    name: Min
  - entity: sensor.outside_temp
    aggregate_func: avg
    name: Avg
    color: green
name: Temp outside daily (last week)
hours_to_show: 168
group_by: date

You can render non-numeric states by providing state_map config. For example this way you can show data coming from binary sensors.

type: custom:mini-graph-card
entities:
  - entity: binary_sensor.living_room_motion
    name: Living room
  - entity: binary_sensor.corridor_motion
    name: Corridor
  - entity: binary_sensor.master_bed_motion
    name: Master bed.
    color: green
  - entity: binary_sensor.bedroom_motion
    name: Bedroom
name: Motion last hour
hours_to_show: 1
points_per_hour: 60
update_interval: 30
aggregate_func: max
line_width: 2
smoothing: false
state_map:
  - value: "off"
    label: Clear
  - value: "on"
    label: Detected

It is possible to show a state without displaying a graph for a sensor. Imagine there are two CO-2 sensors & one humidity sensor; graphs are displayed for the CO-2 only, and the humidity is shown as a state only.

type: custom:mini-graph-card
entities:
  - entity: sensor.xiaomi_cg_1_humidity
    show_state: true
    show_graph: false
  - entity: sensor.xiaomi_cg_1_co2
    color: green
    show_state: false
    name: CO2-1
  - entity: sensor.xiaomi_cg_2_co2
    color: orange
    show_state: false
    name: CO2-2
name: Humidity
hours_to_show: 4
points_per_hour: 60
show:
  name: true
  legend: true
  icon: false
  labels: true

This method may be also used to add a calculated value with it's own aggregate_func option.

When using the attribute option in the entities object, you can access data in structured attributes, such as dictionaries and lists.

Suppose you have data stored inside a dictionary attribute named dict_attribute

dict_attribute:
  value_1: 53
  value_2: 64
  value_3: 72

Such data should be addressed as dict_attribute.sub_attribute:

type: custom:mini-graph-card
entities:
  - entity: sensor.testing_object_data
    attribute: dict_attribute.value_1
    name: value_1 from dictionary attribute

Suppose you have data stored inside a list attribute named list_attribute:

list_attribute:
  - value_1: 67
    value_2: 65
    value_3: 93
  - value_1: 134
    value_2: 130
    value_3: 186
  - value_1: 201
    value_2: 195
    value_3: 279

Such data should be addressed as list_attribute.index.sub_attribute:

type: custom:mini-graph-card
entities:
  - entity: sensor.testing_object_data_list
    attribute: list_attribute.0.value_1
    name: value_1 from first element of list attribute

1. Clone this repository into your config/www folder using git:

$ git clone https://github.com/kalkih/mini-graph-card.git

1. Add a reference to the card in your ui-lovelace.yaml:

resources:
  - url: /local/mini-graph-card/dist/mini-graph-card-bundle.js
    type: module

Requires nodejs & npm.

1. Move into the mini-graph-card repo, checkout the dev branch & install dependencies:

$ cd mini-graph-card && git checkout dev && npm install

1. Make changes to the source code.

2. Build the source by running:

$ npm run build

1. Refresh the browser to see changes.

   Make sure cache is cleared or disabled.

2. (Optional) Watch the source and automatically rebuild on save:

$ npm run watch

The new mini-graph-card-bundle.js will be build and ready inside /dist.

Note that the dev branch is the most up-to-date and matches our beta releases.

Please refer to the Contribution Guidelines if you're interested in contributing to the project. (And thanks for considering!)

Make sure you have javascript_version: latest in your configuration.yaml under frontend:.

Make sure you have the latest versions of mini-graph-card.js & mini-graph-lib.js.

If you have issues after updating the card, try clearing your browser cache.

If you have issues displaying the card in older browsers, try changing type: module to type: js at the card reference in ui-lovelace.yaml.

This project is under the MIT license.