Repository files navigation

This is higly customizable graph card forHome-Assistant's Lovelace UI.

It is based onApexCharts.js and offers most of the features of the library.

It is also inspired by the greatmini-graph-card by@kalkih

However, some things might be broken 😁

• Installation
  • HACS (recommended)
  • Manual install
  • CLI install
  • Add resource reference
• Data processing steps
• Using the card
  • Main Options
  • series Options
  • series'show Options
  • header_actions ortitle_actions options
  • *_action options
  • confirmation options
  • statistics options
  • Mainshow Options
  • header Options
  • now Options
  • group_by Options
  • func Options
  • chart_type Options
  • span Options
  • transform Option
  • data_generator Option
  • yaxis Options. Multi-Y axis
    • Min/Max Format
    • Examples
  • Apex Charts Options Example
  • Layouts
  • Configuration Templates
    • General
    • all_series_config options
• Experimental features
  • Configuration options
  • color_threshold experimental feature
  • hidden_by_default experimental feature
  • brush experimental feature
• Known issues
• Roadmap
• Examples
  • Simple graph
  • Multiple Types of Graphs
  • Aggregating data
  • Compare data from today with yesterday
  • Change the line thickness
  • Use apexcharts-card with auto-entities
  • Change the height of the graph

This card is available inHACS (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 copyapexcharts-card.js from thelatest release into yourconfig/www directory.

2. Add the resource reference as decribed below.

1. Move into yourconfig/www directory.

2. Grabapexcharts-card.js:

$ wget https://github.com/RomRider/apexcharts-card/releases/download/v2.1.2/apexcharts-card.js

3. Add the resource reference as decribed below.

If you configure Lovelace via YAML, add a reference toapexcharts-card.js inside yourconfiguration.yaml:

resources:  -url:/local/apexcharts-card.js?v=2.1.2type: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/apexcharts-card.js and select type "JavaScript Module".
4. Restart Home Assistant.

This diagrams shows how your data goes through all the steps allowed by this card:

⚠️ Since this card is in its debuts, you should expect breaking changes moving forward.⚠️

The card stricly validates all the options available (but not for theapex_config object). If there is an error in your configuration, it will tell you where and display a red error card.

✅means required.

Example:

type:custom:apexcharts-cardseries:  -entity:sensor.indoor_temperatureheader_actions:tap_action:action:call-serviceservice:climate.turn_onservice_data:entity_id:climate.heater

This will popup a dialog box before running the action.

Example:

type:custom:apexcharts-cardseries:  -entity:sensor.indoor_temperatureheader_actions:tap_action:action:call-serviceservice:script.toggle_climateservice_data:entity:climate.heaterconfirmation:text:Are you sure?exemptions:            -user:befc8496799848bda1824f2a8111e30a

The position of the marker will only update when the card updates (state change orupdate_interval).

Span enables you to:

• Offset the graph by an amount of time
• start: Display the graph from the begining of theminute,day,hour,week,month,year. In this case,graph_span should be in most cases<= to 1 unit of the unit defined in start.
• end: Display the graph from the end of theminute,day,hour,week,month,year
• Combined withgroup_by in a serie, the group will begin at the tick of thestart unit (+/-offset if defined)
• Only one ofstart orend is supported at the same time

graph_span:If start is defined, it should be <= to 1 unit of the one defined in `start`span:start:minute, day, hour, week, month or yearend:minute, day, hour, week, month or yearoffset:To offset in the past, prefix with `-` Timerange like 1day, 12h, 10min, -12h, -1d, ...

Eg:

• Display 24h from the start of the current day (00:00 -> 23:59)

  type:custom:apexcharts-cardgraph_span:24hspan:start:day

• Display 24h from the start of the previous day (00:00 -> 23:59, -1 day)

  type:custom:apexcharts-cardgraph_span:24hspan:start:dayoffset:-1d

• Display 12h between 06:00 and 18:00 of the current day

  type:custom:apexcharts-cardgraph_span:12hspan:start:dayoffset:+6h

• Display the last 7 days, the end of the graph is the end of the current day

  type:custom:apexcharts-cardgraph_span:7dspan:end:day

With transform, you can modify raw data comming from Home-Assistant's history using a javascript function.

Some of the things you can do:

• Transform any state into a number (for eg. for binary_sensors)
• Apply a different scale to your data (eg: divide by 1024 to convert bits into Kbits)
• Do anything that javascript allows with the value

Your javascript code will receive:

• x: a state or a value of the attribute if you defined one (it can be astring,null or anumber depending on the entity type you've assigned)
• hass: the fullhass object (hass.states['other.entity'] to get the state object of another entity for eg.)
• entity: the full state object of the entity from the history entry currently being transformed

And should return anumber, afloat ornull.

Some examples:

• Convertbinary_sensor to numbers (1 ison,0 isoff)

  type:custom:apexcharts-cardupdate_delay:3supdate_interval:1minseries:  -entity:binary_sensor.heatingtransform:"return x === 'on' ? 1 : 0;"

• Scale a sensor:

  type:custom:apexcharts-cardupdate_delay:3supdate_interval:1minseries:  -entity:sensor.bandwidthtransform:"return x / 1024;"

Before we start, to learn javascript, google is your friend or ask for help on theforum 🙂

data_generator is an advanced feature. It enables you to build your own data out of the last state of a sensor. It completely bypasses the history retrieval and caching mecanism.

You'll need to write a javascript function which returns a[timestamp, value][]:

• timestamp is the timestamp of the data in ms
• value is the value of the data as a number or a float, make sure you parse it if it's a string.

Inside your javascript code, you'll have access to those variables:

• entity: the entity object
• start (Date object): the start Date object of the graph currently displayed
• end (Date object): the end Date object of the graph currently displayed
• hass: the completehass object
• moment: theMoment.JS object to help you manipulate time and dates

Let's take this example:

• My sensor (sensor.test) has this state as its last state:

  FirstPeak:HighPeakTimes:  -'2021-01-27 03:43:00'  -'2021-01-27 10:24:00'  -'2021-01-27 16:02:00'  -'2021-01-27 22:38:00'  -'2021-01-28 04:21:00'  -'2021-01-28 11:06:00'  -'2021-01-28 16:40:00'  -'2021-01-28 23:18:00'  -'2021-01-29 05:00:00'  -'2021-01-29 11:45:00'  -'2021-01-29 17:19:00'  -'2021-01-29 23:58:00'  -'2021-01-30 05:39:00'  -'2021-01-30 12:25:00'  -'2021-01-30 17:59:00'PeakHeights:  -4.99  -1.41  -4.96  -1.33  -5.22  -1.19  -5.15  -1.14  -5.42  -1.01  -5.3  -0.99  -5.57  -0.87  -5.39unit_of_measurement:mfriendly_name:Tides

• This is data in the future, but I want to display them so I need to build them myself usingdata_generator:

  type:custom:apexcharts-cardgraph_span:4d# I have 4 days worth of data in the future in the attributesspan:start:hour# I want to display from the start of the current hours 4 days into the futureseries:  -entity:sensor.testdata_generator:|# This is what builds the data      return entity.attributes.PeakTimes.map((peak, index) => {        return [new Date(peak).getTime(), entity.attributes.PeakHeights[index]];      });

  The result of this function call would be something like:
  [[1611718980000, 4.99], [1611743040000, 1.41], [1611763320000, 4.96], ...]

• And this is all you need 🎉

⚠️ If this option is used, you can't defineyaxis in the mainapex_config option as it will be overriden.

You can have as many y-axis as there are series defined in your configuration or less.

min andmax support multiple types of format:

• not set orauto (this is the default): if it is set toauto, the min or max will be automatically calculated
• any number: if a number is set, the min or max will be fixed on the y-axis
• ~90: if the format is~ followed by a number, the min or max will be defined as a soft bounds
  • min: ~90 and the min of the data in the series is120: the y-axis min value will be90
  • min: ~90 and the min of the data in the series is60: the y-axis min value will be60
• '|+20|' or'|-20|': This will add/remove the value between| | from the min/max
  • min: '|-20|': The min of the data in the series is32, the y-axis min will be12 (=32 - 20)
  • max: '|+10|': The max of the data in the series is32, the y-axis max will be42 (=32 + 10)

• Simple example with one y-axis:

  type:custom:apexcharts-cardheader:show:truetitle:Max Soft Bounds + Min Fixed Boundgraph_span:20minseries:  -entity:sensor.random0_100yaxis:# only 1 yaxis, no need for id or yaxis_id  -min:0# if the sensor doesn't go above 50, the max of the axis will be 50# else the max will be the maximum value of the sensormax:~50decimals:0apex_config:tickAmount:4

• In this example, we have 2 sensors:

  • sensor.random0_100: goes from0 to100
  • sensor.random_0_1000: goes from0 to1000

  Themin andmax of both y-axis are auto calculated based on the spread of the data associated with each axis.

  

  type:custom:apexcharts-cardgraph_span:20minyaxis:  -id:first# identification name of the first y-axisdecimals:0apex_config:tickAmount:4  -id:second# identification name of the second y-axisopposite:true# make it show on the right sidedecimals:0apex_config:tickAmount:4all_series_config:stroke_width:2series:  -entity:sensor.random0_100yaxis_id:first# this serie will be associated to the 'id: first' axis.  -entity:sensor.random_0_1000yaxis_id:second# this serie will be associated to the 'id: second' axis.  -entity:sensor.random0_100yaxis_id:first# this serie will be associated to the 'id: first' axis.transform:'return Number(x) + 30;'# We make it go fom 30 to 130  -entity:sensor.random0_100yaxis_id:first# this serie will be associated to the 'id: first' axis.transform:'return Number(x) - 30;'# We make it go from -30 to 70

This is how you could change some options from ApexCharts as described on theOptions (Reference) menu entry.

Hundreds of options are available and it is not possible to describe them all here so check over there and ask on theforum if you need help with using them.

• ⚠️ Some options might not work in the context of this card.
• ⚠️ Everything which is available through the default config of this card shouldn't be defined inapex_config. If you do, it might break.

type:custom:apexcharts-cardseries:  -...apex_config:dataLabels:enabled:truedropShadow:enabled:true

Some options in ApexCharts can take a javascript function as an argument. To make this possible, you'll have to prefix your function withEVAL:.

⚠️ While using thisEVAL: feature, there is no safeguard so use at your own risk.

Here is an example:

apex_config:yaxis:labels:formatter:|        EVAL:function(value) {          return "42";        }

For now, onlyminimal is supported: It will remove the grid, the axis and display the legend at the top. But you can use theapex_config to do whatever you want.

• minimal

  

For code junkies, you'll find the default options I use insrc/apex-layouts.ts

• Define your config template in the main lovelace configuration and then use it in your cards. This will avoid a lot of repetitions! It's basically YAML anchors, but without using YAML anchors and is very useful if you split your config in multiple files 😄

• You can overload any parameter with a new one

• Arrays will be merged by matching the index

• You can also inherit another template from within a template.

• You can inherit multiple templates at once by making it an array. In this case, the templates will be merged together with the current configuration in the order they are defined. This happens recursively.

  type:custom:apexcharts-cardconfig_templates:  -template1  -template2# ortype:custom:apexcharts-cardconfig_templates:template1

The card templates will be applied in the order they are defined:template2 will be merged withtemplate1 and then the local config will be merged with the result. You can still chain templates together (ie. define template in a apexcharts-card template. It will follow the path recursively).

Make sure which type of lovelace dashboard you are using before changing the main lovelace configuration:

• managed changes are managed by lovelace UI - add the template configuration to configuration in raw editor
  • go to your dashboard
  • click three dots andEdit dashboard button
  • click three dots again and clickRaw configuration editor button
• yaml - add template configuration to your dashboard file (ui-lovelace.yaml for eg.)

Note: Templates have to be defined in all dashboards, they are not shared.

To give you an idea where to put those (in your dashboard file/RAW editor):

apexcharts_card_templates:default:color_list:['red', 'green', 'blue']bandwidth_chart:graph_span:24hconfig_templates:defaultheader:show:trueshow_states:truecolorize_states:trueall_series_config:stroke_width:2opacity:0.3type:areaviews:  -title:Mainpanel:truecards:[...]

And then where you define your card, you can consume those templates, and/or overload it:

-type:custom:apexcharts-cardconfig_templates:bandwidth_chartheader:title:WAN Bandwidthseries:    -entity:sensor.wan_download    -entity:sensor.wan_uploadinvert:true

In the end, this would produce the same result as but it's shorter and you can reuse that template elsewhere:

-type:custom:apexcharts-cardgraph_span:24hheader:title:WAN Bandwidthshow:trueshow_states:truecolorize_states:trueall_series_config:stroke_width:2opacity:0.3type:areacolor_list:['red', 'green', 'blue']series:    -entity:sensor.wan_download    -entity:sensor.wan_uploadinvert:true

This will allow you to apply some settings to all the series avoiding repetition. It's just syntaxic sugar and doesn't add more features.

Eg:

-type:custom:apexcharts-cardgraph_span:24hall_series_config:stroke_width:2type:areatransform:return x / 1024;unit:Mb/sseries:    -entity:sensor.wan_download    -entity:sensor.wan_uploadinvert:true

Generates the same result as repeating the configuration in each series:

-type:custom:apexcharts-cardgraph_span:24hseries:    -entity:sensor.wan_downloadstroke_width:2type:areatransform:return x / 1024;unit:Mb/s    -entity:sensor.wan_uploadinvert:truestroke_width:2type:areatransform:return x / 1024;unit:Mb/s

⚠️ You enter the danger zone⚠️

color_threshold is an experimental feature for now since enabling it will break some other default features.

If enabled, it might:

• display the wrong serie color in the tooltip in some cases (series with datapoints not aligned mostly)
• display thin columns instead of the standard size
• completely renderapex_config.fill options unusable, and if you do, it will break the card

Now that you are warned, it works with:

• chart_type:radialBar,line,pie,donut
• series'stype:column,area,line

Some notes:

• Forseries'stype: column, the full bar will be of the color defined. Gradient is not possible
• Forseries'stype: area:
  • only the filled area will be displayed with the gradient. It is not possible to do so for the line.
  • It works better withstroke_width: 1 orstroke_width: 0
• If usinginvert: true, the values incolor_threshold should stay the same as withinvert: false.

And this is how to use it:

type:custom:apexcharts-cardexperimental:color_threshold:trueseries:  -entity:sensor.temperaturecolor_threshold:      -value:-10# color can be a color name, rgb(r, g, b), '#0000ff' or var(--color-variable)# default is: the default color of the seriecolor:blue# optional opacity, value from 0 to 1.# only for line and area# Default is 1 for 'type: line' and 0.7 for `type: area`opacity:1      -value:0color:cyan      -value:15color:green      -value:25color:orange

Enabling this experimental feature might/will break the auto-scaling and auto-column width feature. Don't open an issue for that. It only works if all the series have a unique name.

This option is useful if you want to hide a serie from the chart by default when it's loaded as if you had clicked on the legend to disable this serie.

This is how to use it:

type:custom:apexcharts-cardexperimental:hidden_by_default:trueseries:  -entity:sensor.temperatureshow:hidden_by_default:true  -entity:sensor.temperature_office

brush will allow you to display a small chart on the bottom of the card to select a time frame to display on the main chart.

Things to know:

• You might have some glitches if you are using colums in either the top or the bottom of the chart. There's nothing I can do about it.
• All the features from normal series can be applied to the brush series
• You can configure the bottom chart the way you want with another specificapex_config also
• It might be compute heavy and slow with a lot of history data points
• It is recommended to not show too much data on the bottom chart for the sake of lisibility

Here is how to use it (this represents the chart above):

type:custom:apexcharts-cardexperimental:color_threshold:truebrush:true# This is requiredgraph_span:2h# This will represent the span of the brushbrush:# selection_span: optional# defines the default selected span in the brush# Defaults to 1/4 of the `graph_span`selection_span:10m# apex_config: optionalapex_config:# Any ApexCharts settings you want to apply to the brush# Same as the standard apex_configseries:  -entity:sensor.random0_100color:bluetype:areastroke_width:1color_threshold:      -value:0color:red      -value:50color:yellow      -value:100color:green  -entity:sensor.random0_100color:bluestroke_width:1float_precision:0show:# in_brush: set it to true and the serie will show up in the brushin_brush:true# add this also if you want your serie to only show up in the brushin_chart:false

• Sometimes, ifsmoothing is used alongsidearea and there is missing data in the chart, the background will be glitchy. Seeapexcharts.js/#2180
• binary_sensor is not yet supported.
• Bars will span left and right of the data point. Not so great if you usefunc to aggregate your data. Seeapexcharts.js/#1688

Not ordered by priority:

• Support more types of charts (pie, radial, polar area at least)
• Support forbinary_sensors
• Support for aggregating data with exact boundaries (ex: aggregating data with1h could aggregate from2:00:00am to2:59:59am then3:00:00am to3:59:59 exactly, etc...)
• Display the graph from start of day, week, month, ... with support for "up to now" or until the "end of the period"
• Support for any number of Y-axis
• Support for logarithmic
• Support for state mapping for non-numerical state sensors
• Support for simple color threshold (easier to understand/write than the ones provided natively by ApexCharts)
• Support for graph configuration templates à labutton-card

type:custom:apexcharts-cardseries:  -entity:sensor.temperature

type:custom:apexcharts-cardgraph_span:6hheader:show:falseseries:  -entity:sensor.humiditytype:linename:Outside Humiditygroup_by:func:avgduration:30min  -entity:sensor.random0_100type:columnname:Office Humiditygroup_by:func:avgduration:30min

type:custom:apexcharts-cardgraph_span:1hheader:show:falseseries:  -entity:sensor.random0_100name:AVGcurve:smoothtype:linegroup_by:duration:10minfunc:avg  -entity:sensor.random0_100curve:smoothname:MINtype:linegroup_by:duration:10minfunc:min  -entity:sensor.random0_100curve:smoothname:MAXtype:linegroup_by:duration:10minfunc:max  -entity:sensor.random0_100curve:smoothname:LASTtype:linegroup_by:duration:10minfunc:last  -entity:sensor.random0_100curve:smoothname:FIRSTtype:linegroup_by:duration:10minfunc:first

type:custom:apexcharts-cardgraph_span:1dspan:start:dayheader:show:falseseries:# data from today  -entity:sensor.temperature# data from yesterday offsetted to be displayed today  -entity:sensor.temperatureoffset:-1d

• Change all lines thickness

  type:custom:apexcharts-cardgraph_span:1dall_series_config:stroke_width:2series:  -entity:sensor.temperature  -entity:sensor.humidity

• Selective line thickness modification

  type:custom:apexcharts-cardgraph_span:1dseries:  -entity:sensor.temperaturestroke_width:2  -entity:sensor.humiditystroke_width:6

This requires theauto-entities card

type:custom:auto-entitiesfilter:include:    -entity_id:sensor.temperature*options:entity:this.entity_idcard:type:custom:apexcharts-card

This is described in the ApexCharts.js documentationhere where you can find way more options.

type:custom:apexchart-cardapex_config:chart:height:250pxseries:  -entity:sensor.temperature