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

Mushroom 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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

Advertisement Advertisement

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.

Show 24h worth of data

type: custom:apexcharts-card graph_span: 24h
Code language: YAML (yaml)

Show 7 days worth of data

type: custom:apexcharts-card graph_span: 7d
Code language: YAML (yaml)
  • span:
    Define the start, end and offset of displayed data selected with graph_span.

Show today’s data

type: custom:apexcharts-card graph_span: 24h span: start: day ..
Code language: YAML (yaml)

Show yesterday’s data

type: custom:apexcharts-card graph_span: 24h span: start: day offset: -1d
Code language: YAML (yaml)

Show last 30 days worth of data in a line chart

type: custom:apexcharts-card graph_span: 30d span: end: day ..
Code language: YAML (yaml)

Show last calendar week data in a line chart 

type: custom:apexcharts-card graph_span: 1w span: end: isoWeek offset: -1week
Code language: YAML (yaml)

Show 7 days worth of data grouped in a column by day ending with today

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
Code language: YAML (yaml)

Show 4 weeks worth of data grouped in a column by calendar week ending with current week

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
Code language: YAML (yaml)
  • transform:
    Modify raw data coming from Home-Assistant’s history database using a JavaScript function

Convert binary_sensor to numbers (1 is on, 0 is off)

type: custom:apexcharts-card series: - entity: binary_sensor.dishwasher transform: "return x === 'on' ? 1 : 0;"
Code language: YAML (yaml)

Scale a sensor’s data

type: custom:apexcharts-card series: - entity: sensor.download_kb transform: "return x / 1024;"
Code language: YAML (yaml)

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.

Advertisement Advertisement

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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.

Advertisement Advertisement

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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

Advertisement Advertisement

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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
Code language: YAML (yaml)

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


You can support this blog by buying us a coffee!

Leave a Comment

Your email address will not be published.

DISCLOSURE
SmartHomeScene.com is a participant in the Amazon Services LLC Associates Program and AliExpress Portals Affiliate Program. These programs are designed to provide means for websites to earn revenue by linking affiliate products through their content. We are compensated for referring traffic and business to these websites.
SmartHomeScene.com

Scroll to Top