ApexCharts Tutorial: Advanced Graphs for your Home Assistant UI

In a recent tutorial, we used the Mushroom Cards collection and showed you how to create a minimalistic and clean Home Assistant dashboard. Today we are tackling the ApexCharts Card by dev RomRider, which is based on ApexCharts.js, an open-source charting library.

Many of us have been using the excellent Mini Graph Card by kalkih to display data in a simple graph in our Home Assistant dashboards. It has a clean, minimalistic look and feel to it and presents history information nicely in Lovelace UI. The Apex Charts Card is like its Big Brother: It dwarfs it in customization variables and data processing capabilities.

This heavily customizable custom card is capable of creating extremely advanced charts in the shape of a line, columns, donut charts, pie charts, scatter graphs and radial bar charts. The ApexCharts Card does not include a built-in UI editor, so you will need to use YAML.

We will go over the card installation and basic config, provide many examples, so you can copy-paste directly to your Lovelace UI and adjust it to your needs.

UPDATE v2.0.0: extend_to_end has been removed and replaced by extend_to with support for now and end.

Installation

HACS

ApexCharts is available in HACS (Home Assistant Community Store).

1. Open HACS
2. Go to “Frontend” section
3. Click button with “+” icon
4. Search for “ApexCharts”

Manual

1. Download apexcharts-card.js file from the [latest-release].
2. Put apexcharts-card.js file into your config/www folder.
3. Add reference to apexcharts-card.js in Lovelace. There’s two way to do that:

• Using UI: Configuration → Lovelace Dashboards → Resources Tab → Click Plus button → Set Url as /local/apexcharts-card.js → Set Resource type as JavaScript Module. 
  Note: If you do not see the Resources Tab, you will need to enable Advanced Mode in your User Profile
• Using YAML: Add following code to lovelace section

resources:
    - url: /local/apexcharts-card.js
      type: module

CLI Install

1. Move into your config/www directory.
2. Grab apexcharts-card.js:
3. Add the resource in your lovelace section (as above)

$ wget https://github.com/RomRider/apexcharts-card/releases/download/v1.10.0/apexcharts-card.js

Cards Configuration Variables

The ApexCharts Custom Card has an incredible amount of configuration variables, to style and configure the card according to your needs. For the purpose of the length of this tutorial, we are not going to list every single one of them on this blog. Instead, we are going to try to cover most of them through examples in code syntax. You can check all this card has to offer HERE.

Important Variables

To be able to understand how ApexCharts displays data, we will explain some of the most important configuration variables through examples. We are not going to focus too much on cosmetic options, but more on data processing and display options. 

The graph_span and span options are used to choose which data will be fetched for the the ApexCharts to process. 

The group_by function organizes the data by a specific function (last, min, max, mean…), builds buckets of data by setting duration (10sec, 1min, 7d…), and can fill missing history data.

The transform function can modify raw data coming from HA’s history database using JavaScript.
Example: Display a binary_sensor data as a number. See more HERE.

The data_generator function is an advanced feature which enables you to build your own data out of the last state of a sensor. It completely bypasses the history retrieval and caching mechanism. See more HERE.

• graph_span:
  The span of the graph as a time interval.

type: custom:apexcharts-card
graph_span: 24h

type: custom:apexcharts-card
graph_span: 7d

• span:
  Define the start, end and offset of displayed data selected with graph_span.

type: custom:apexcharts-card
graph_span: 24h
span:
  start: day
  ..

type: custom:apexcharts-card
graph_span: 24h
span:
  start: day
  offset: -1d

type: custom:apexcharts-card
graph_span: 30d
span:
  end: day
  ..
  

type: custom:apexcharts-card
graph_span: 1w
span:
  end: isoWeek
  offset: -1week

type: custom:apexcharts-card
graph_span: 7d
span:
  end: day
series:
  - entity: sensor.stove_time_on_today
    type: column
    group_by:
      func: last
      duration: 1d    

type: custom:apexcharts-card
graph_span: 28d
span:
  end: isoWeek
series:
  - entity: sensor.stove_time_on_today
    type: column
    group_by:
      func: last
      duration: 7d

• transform:
  Modify raw data coming from Home-Assistant’s history database using a JavaScript function

type: custom:apexcharts-card
series:
  - entity: binary_sensor.dishwasher
    transform: "return x === 'on' ? 1 : 0;"

type: custom:apexcharts-card
series:
  - entity: sensor.download_kb
    transform: "return x / 1024;"

Usage Examples

This custom card can be used to present data in Lovelace from various sources, from different types of entities or their attributes. We going to cover the most common entity types and their advanced configuration.

Note: In some of the examples of this tutorial, we are using card-mod to further style the cards.

Line, Column, Area

To display temperature data for a specific room in the last 24hours, we use the default line graph. When chart_type is unset, the card defaults to this graph. This chart type has 3 subtypes which can be applied under the series function: Line, Column and Area. For example, we set the span to day, add some custom colors in color_threshold and set our entities under the series variable:

type: custom:apexcharts-card
experimental:
  color_threshold: true
graph_span: 24h
show:
  last_updated: true
header:
  standard_format: false
  show: true
  show_states: true
  colorize_states: true
  title: Living Room Temperature
span:
  start: day
series:
  - entity: sensor.living_room_temperature
    type: line
    group_by:
      func: last
      duration: 15m
    stroke_width: 5
    show:
      header_color_threshold: true
    color_threshold:
      - value: 18
        color: steelblue
      - value: 21
        color: midnightblue
      - value: 22
        color: orange
      - value: 23
        color: orangered
      - value: 24.5
        color: red

We can further customize the chart by adding the humidity entity, adding a “Now” marker to show our current time of day and adding extremas, to show the minimum and maximum values of our sensor.

type: custom:apexcharts-card
experimental:
  color_threshold: true
graph_span: 24h
show:
  last_updated: true
header:
  standard_format: false
  show: true
  show_states: true
  colorize_states: true
  title: Living Room Temperature
now:
  show: true
  color: red
  label: Now
span:
  start: day
series:
  - entity: sensor.living_room_temperature
    type: line
    group_by:
      func: last
      duration: 15m
    stroke_width: 5
    show:
      extremas: true
      header_color_threshold: true
    color_threshold:
      - value: 18
        color: steelblue
      - value: 21
        color: midnightblue
      - value: 22
        color: orange
      - value: 23
        color: orangered
      - value: 24.5
        color: red
  - entity: sensor.living_room_humidity
    show:
      in_chart: true

We can convert the chart to a column type or an area graph type. We can also add a custom chart height under apex_config and remove card backgrounds and borders with card-mod. 

type: custom:apexcharts-card
style: |
  ha-card {
    background-color: var(--primary-primary-color);
    box-shadow: none;
  }
apex_config:
  chart:
    height: 170px
.....    
series:
  - entity: sensor.living_room_temperature
    type: column   
  - entity: sensor.living_room_humidity
    type: area    

Radial Bar Chart

A Radial Bar can be used to show percentage with predefined min-max values, which must be provided for each series displayed as it requires to convert the value into percentage. If undefined, the default value for min is 0 and for max is 100. This graph works well if you want to display sensors natively in percentages.

type: custom:apexcharts-card
header:
  show: true
  title: Temperature Levels
  show_states: true
  colorize_states: true
chart_type: radialBar
series:
  - entity: sensor.bathroom_battery_level
    name: Bathroom
  - entity: sensor.bedroom_battery_level
    name: Bedroom
  - entity: sensor.kitchen_battery_level
    name: Kitchen

Pie Chart

This chart will display a pie-shaped chart with the last value computed of each sensor. In my example, I used sensors created from the utility meter integration to show energy consumption.

type: custom:apexcharts-card
chart_type: pie
header:
  show: true
  show_states: true
  colorize_states: true
  title: Monthly energy consumption in kWH
series:
  - entity: sensor.dishwasher_kwh_monthly_economic
    name: Dishwasher Economic
  - entity: sensor.dishwasher_kwh_monthly_regular
    name: Dishwasher Regular
  - entity: sensor.washer_kwh_monthly_economic
    name: Washer Economic
    type: column
  - entity: sensor.washer_kwh_monthly_regular
    name: Washer Regular
  - entity: sensor.dryer_kwh_monthly_economic
    name: Dryer Economic
  - entity: sensor.dryer_kwh_monthly_regular
    name: Dryer Regular
    type: column

Donut Chart

The donut chart is essentially the same as the pie chart, only with a hole in the middle. In my example, it uses simple template sensors to calculate energy consumption based on electricity price.

Note: Values in pictures are not correct, simply modified to show the chart usage.

type: custom:apexcharts-card
chart_type: donut
header:
  show: true
  show_states: true
  colorize_states: true
  title: Daily energy consumption in USD
series:
  - entity: sensor.dishwasher_usd_daily
    name: Dishwasher
    type: column
    unit: ' USD'
    color: darkviolet
  - entity: sensor.washer_usd_daily
    name: Washer
    type: column
    unit: ' USD'
    color: midnightblue
  - entity: sensor.dryer_usd_daily
    name: Dryer
    unit: ' USD'
    color: orangered

Scatter Chart

The scatter chart can be used to display a cloud of points, without a line connecting them. When using this chart, be sure to always set the group_by function to something larger than default, because if you have a lot of data with noisy sensors, the chart will get overwhelmed and make no sense.

type: custom:apexcharts-card
chart_type: scatter
experimental:
  color_threshold: true
graph_span: 24h
show:
  last_updated: true
header:
  standard_format: false
  show: true
  show_states: true
  colorize_states: true
  title: Living Room Ambient
span:
  start: day
series:
  - entity: sensor.living_room_temperature
    group_by:
      func: last
      duration: 1h
    show:
      header_color_threshold: true
    color_threshold:
      - value: 18
        color: steelblue
      - value: 21
        color: midnightblue
      - value: 22
        color: orange
      - value: 23
        color: orangered
      - value: 24.5
        color: red
  - entity: sensor.living_room_humidity

More Examples

Total Stove Heating Time

When hovered, the ApexCharts Card displays your span and state. We can define the y-axis min and max values and set the tick amount. You can find more about y-axis HERE.

type: custom:apexcharts-card
apex_config:
  chart:
    height: 170px
experimental:
  color_threshold: true
graph_span: 7d
span:
  end: day
show:
  last_updated: true
header:
  show: true
  show_states: true
  colorize_states: true
  title: Total Time Heating Per Day
yaxis:
  - min: 0
    max: ~11
    decimals: 0
    apex_config:
      tickAmount: 5
series:
  - entity: sensor.thermoflux_time_on_today
    show:
      header_color_threshold: true
      extremas: true
      as_duration: hour
    type: column
    name: Duration
    group_by:
      func: last
      duration: 1d
    color_threshold:
      - value: 1
        color: dodgerblue
      - value: 3
        color: darkcyan
      - value: 5
        color: goldenrod
      - value: 7
        color: orangered
      - value: 10
        color: darkred

To get a weekly chart, replace the following variables:

type: custom:apexcharts-card
graph_span: 56d
span:
  end: isoWeek
.....
series:
  - entity: sensor.thermoflux_time_on_today
    group_by:
      func: last
      duration: 7d  

Raspberry Pi Monitor

To monitor processor usage and temperate, we can use the line graph.

type: custom:apexcharts-card
experimental:
  color_threshold: true
graph_span: 24h
show:
  last_updated: true
  loading: false
header:
  standard_format: false
  show: true
  show_states: true
  colorize_states: true
  title: Raspberry Pi 4 CPU
now:
  show: true
  color: red
  label: Now
span:
  start: day
series:
  - entity: sensor.processor_use_percent
    name: Processor Usage
    stroke_width: 5
    group_by:
      duration: 30sec
    show:
      extremas: true
      header_color_threshold: true
  - entity: sensor.processor_temperature
    stroke_width: 5
    group_by:
      duration: 30sec
    show:
      extremas: true
      header_color_threshold: true

To monitor disk usage and memory usage, we can use a RadialBar graph:

type: custom:apexcharts-card
apex_config:
  chart:
    height: 355px
header:
  show: true
  title: Raspberry Pi4 System Monitor
  show_states: true
  colorize_states: true
chart_type: radialBar
series:
  - entity: sensor.disk_use
    name: Disk Used
    show:
      in_chart: false
  - entity: sensor.disk_free
    name: Disk Free
    show:
      in_chart: false
  - entity: sensor.disk_use_percent
    name: Disk Used (%)
    show:
      in_header: false
  - entity: sensor.memory_use
    name: Memory Used
    show:
      in_chart: false
  - entity: sensor.memory_free
    name: Memory Free
    show:
      in_chart: false
  - entity: sensor.memory_use_percent
    name: Memory Used (%)
    show:
      in_header: false

Utility Meter

We can stack the utility meter data, for a daily per device overview spanning 14 days. When hovered it will give us exact data of each appliance monitor in our example along with the correct day.

Note: Values in pictures are not correct, simply modified to show the chart usage.

type: custom:apexcharts-card
apex_config:
  chart:
    stacked: true
graph_span: 14d
span:
  end: day
show:
  last_updated: true
header:
  show: true
  show_states: true
  colorize_states: true
  title: Daily energy consumption in USD
series:
  - entity: sensor.dishwasher_usd_daily
    name: Dishwasher
    type: column
    unit: ' USD'
    color: darkviolet
    group_by:
      func: max
      duration: 1d
  - entity: sensor.washer_usd_daily
    name: Washer
    type: column
    unit: ' USD'
    color: slateblue
    group_by:
      func: max
      duration: 1d
  - entity: sensor.dryer_usd_daily
    name: Dryer
    type: column
    unit: ' USD'
    color: orangered
    group_by:
      func: max
      duration: 1d

Minimal Layout

The ApexCharts card offers a minimal layout which removes the grid, the axis and display the legend at the top. You can combine this clean layout with any types of chart to display it to your liking. For example:

type: custom:apexcharts-card
layout: minimal
graph_span: 24h
header:
  standard_format: false
  show: true
  title: Living Room Ambient
span:
  start: day
series:
  - entity: sensor.living_room_temperature
    color: orangered
    type: line
    group_by:
      func: last
      duration: 15m
    stroke_width: 5
    show:
      extremas: true
      header_color_threshold: true
  - entity: sensor.living_room_humidity
    type: area
    show:
      in_chart: true
    group_by:
      func: last
      duration: 15m

Instead of a line and area, we can change the type variable to display a column and a line:

type: custom:apexcharts-card
layout: minimal
graph_span: 24h
header:
  standard_format: false
  show: true
  title: Bedroom Ambient
span:
  start: day
series:
  - entity: sensor.bedroom_temperature
    color: orangered
    type: column
    group_by:
      func: last
      duration: 30min
    stroke_width: 5
    show:
      extremas: true
      header_color_threshold: true
  - entity: sensor.bedroom_humidity
    type: line
    show:
      in_chart: true
    group_by:
      func: last
      duration: 30m

Summary

The ApexCharts Card includes so many configuration variables, it is impossible to cover all of them in a single tutorial. I hope that the examples we provided will benefit some you so you can copy-paste and adjusts them to your needs.

Because it is based on the open-source charting library ApexCharts.js, it can be customized to infinity. You can check all the options this library offers HERE.

Developer RomRider notes that since this card is in its early stages of development, some bugs or breaking changes may occur. It’s worth noting that in my usage so far, I have encountered none.

Screenshots