Skip to content

Home

Jump to bottom
remmob edited this page Mar 7, 2026 · 5 revisions

Home

Table of Contents

Features

Feature Description
Line & Bar Charts Supports both line and bar chart types
Multiple Series Visualize multiple sensors/entities on one chart
Fill Toggle Enable/disable area fill per series
Right Y-Axis Assign series to right Y-axis
Interactive Legend Show/hide series, always at least one visible
Axis Title Position Fully configurable via offset options
Custom Time Selector Flexible time range buttons, including custom, 48h, 72h
Auto-Refresh Periodic data refresh
Download Export chart as PNG, SVG, JPEG, WebP
Modebar Styling Customizable Plotly toolbar
Status Text Optional status/tooltip line
Advanced Styling Extensive color, font, and layout controls

⚡ Quick Highlight: Energy Selector Changes

Behavior

  • Energy mode uses selector controls for week, month, and year.
  • Year list is dynamic: 2020 to current year.
  • Month and week selectors follow the chosen year.
  • One per-card property for custom visibility: show_custom_button.

Key options

Option Type Default Description
energy_time_ranges list [today, week, month, year, custom] Energy mode selector list
show_custom_button boolean true Show/hide Custom for this card
select_background_color string button bg Selector background color
select_text_color string button text Selector text color
select_border_color string button border Selector border color
select_active_background_color string active bg Active selector background
select_active_border_color string active border Active selector border
select_active_text_color string active text Active selector text
select_option_background_color string select bg Dropdown option background
select_option_text_color string select text Dropdown option text
select_label_color string button text Selector label color
show_bar_values boolean true Show value labels on energy bar charts (0-values stay hidden by default)
bar_value_position string inside Position of bar value labels: inside or outside
bar_value_decimals number 2 Number of decimals in bar value labels
bar_value_min_width_px number 28 Minimum bar width for horizontal label
bar_value_font_size number 11 Bar value label font size
bar_value_text_color string bar_value_font_color Preferred bar value label text color alias
bar_value_font_color string font_color Bar value label text color
totals_decimals number bar_value_decimals Decimals used in totals boxes
series_total_box_width string 108px Fixed width of each totals box

Example

type: custom:timescale-plotly-card
energy_mode: true
time_mode: energy_calendar
energy_time_ranges: [today, week, month, year]
show_custom_button: false

show_bar_values: true
bar_value_position: inside
bar_value_text_color: var(--primary-text-color)
totals_decimals: 2
series_total_box_width: 108px

select_background_color: var(--primary-background-color)
select_text_color: var(--primary-text-color)

Configuration Options

Option Description
sensor_id Single sensor entity to plot
entities List of multiple series (see example)
chart_type line or bar
fill Enable/disable area fill per series
yaxis left or right per series
yaxis_title Y-axis title (set to NaN or omit to hide)
yaxis_title_left Override left Y-axis title
yaxis_title_right Override right Y-axis title
axis_title_offset_y Vertical offset for axis titles
axis_title_offset_left Horizontal offset for left axis title
axis_title_offset_right Horizontal offset for right axis title
show_time_selector Show/hide time range buttons
time_ranges List of time range buttons.
Tip: You can add any hour interval you want, such as 4h, 5h, 10h, etc. The card supports all valid numbers followed by h without any code changes.
show_custom_button Show/hide custom range button
default_range Default time range
auto_refresh Auto-refresh interval (seconds)
... See README for full list

Optional Cross-Card Sync

If you do not want sync, do not set sync keys. Without sync_group, each card works independently (original behavior).

Option Description
sync_group Group name used to sync time/range state between cards
sync_mode Sync role: master, follower, both, off
sync_role Alias of sync_mode

Master/follower example:

type: custom:timescale-plotly-card
title: Energie master
sync_group: energie_sync
sync_mode: master
show_time_selector: true
type: custom:timescale-plotly-card
title: Energie follower
sync_group: energie_sync
sync_mode: follower
show_time_selector: false

Energy Calendar Mode

Enable with time_mode: energy_calendar or energy_mode: true.

Option Description
time_mode Set energy_calendar for energy calendar behavior
energy_mode Alternative boolean switch for energy calendar mode
energy_time_ranges Selector options in energy mode
energy_year / energy_month / energy_day / energy_week Initial selected calendar values
energy_bucket Bucket size for fixed windows (15m, 1h, 1d)
energy_week_start Week start day (0=Sunday, 1=Monday, ... 6=Saturday)
energy_years_count Number of years in years range
energy_years_offset Offset for years range window
energy_downsample Downsample override for energy mode
energy_source_type Source interpretation: delta or cumulative
energy_cumulative_mode Cumulative handling mode
energy_handle_reset Handle resets in cumulative counters

Chart Types

  • Line Chart: Default, smooth time series visualization.
  • Bar Chart: Use chart_type: bar for column-style visualization.

Example Configurations

Single Sensor Example

# TimescaleDB Plotly Card - Single Sensor Example
 type: custom:timescale-plotly-card
 sensor_id: sensor.temperature_woonkamer
 title: Temperature Living Room
 chart_type: line
 fill: true
 line_color: rgb(75, 192, 192)
 axis_title_offset_y: 100px
 axis_title_offset_left: 20px
 axis_title_offset_right: 40px
 time_ranges: [1h, 2h, 6h, 12h, 24h, 48h, 72h, custom]
 show_time_selector: true
 auto_refresh: 300

Multiple Series Example

# TimescaleDB Plotly Card - Multiple Series Example
 type: custom:timescale-plotly-card
 title: Living Room Climate
 entities:
   - sensor_id: sensor.temperature_woonkamer
     name: Temperature
     line_color: rgb(255, 99, 132)
     fill_color: rgba(255, 99, 132, 0.2)
     fill: true
   - sensor_id: sensor.humidity_woonkamer
     name: Humidity
     line_color: rgb(54, 162, 235)
     fill_color: rgba(54, 162, 235, 0.2)
     yaxis: right
     fill: false
 chart_type: bar
 axis_title_offset_y: 100px
 axis_title_offset_left: 20px
 axis_title_offset_right: 40px
 time_ranges: [1h, 2h, 6h, 12h, 24h, 48h, 72h, custom]
 show_time_selector: true
 auto_refresh: 300

Database Selection

The card supports database selection at both the card and per-series level. This is useful if you have multiple TimescaleDB databases (for example, LTSS and Scribe).

Card Level

type: custom:timescale-plotly-card
database: ltss  # or scribe
sensor_id: sensor.temperature_woonkamer

Per-Series Level

type: custom:timescale-plotly-card
title: Living Room Climate
entities:
  - sensor_id: sensor.temperature_woonkamer
    name: Temperature
    database: ltss
  - sensor_id: sensor.amber_4h_average_ambient_temperature
    name: Outdoor temp 4h average
    database: scribe

If both the card and a series specify a database, the series setting takes precedence.

Options

Option Type Level Description
database string card/series Database name as configured in Timescale Database Reader

Styling & Layout

  • All colors, fonts, backgrounds, and margins are configurable.
  • Modebar, buttons, tooltips, and status text can be styled via YAML options.
  • Axis titles are positioned using offset options for pixel-perfect placement.

Advanced Usage

  • Hide axis titles by setting to NaN or omitting.
  • Always at least one legend item visible.
  • Custom time selector with flexible button list.
  • Download chart in multiple formats.
  • Bar chart support for grouped/stacked data.

Per-series gap/interpolation options

You can now control how missing data/gaps are handled per series:

Option Type Level Default Description
connect_gaps boolean series/card false Connect missing points to form a continuous line (also for tooltips/interpolation)
extend_edge_gaps boolean series/card false Visually extend the first/last value to the chart edge
nan_as_zero boolean series/card false Treat missing values as 0
gap_drop_to_zero boolean series/card false Draw a vertical line to 0 at a gap
gap_drop_min_points number series/card 2 Minimum consecutive missing points before dropping to 0

Example:

type: custom:timescale-plotly-card
title: Livingroom
entities:
  - sensor_id: sensor.temperature_woonkamer
    name: Living room temperature
    connect_gaps: true           # Connect line over gaps
    extend_edge_gaps: true       # Extend edges
    nan_as_zero: false           # Do not treat nulls as 0
    gap_drop_to_zero: false      # No drop to 0
  - sensor_id: sensor.amber_4h_average_ambient_temperature
    name: Outdoor temp 4h average
    connect_gaps: false
    extend_edge_gaps: false
    nan_as_zero: true            # Treat missing values as 0
    gap_drop_to_zero: true       # Drop to 0 at gap
    gap_drop_min_points: 3       # Only for 3+ missing points

These options can also be set globally, but per-series settings override the global value.

FAQ

Q: How do I hide an axis title? A: Set the title to NaN or leave it out of the config.

Q: Can I use bar charts? A: Yes, set chart_type: bar.

Q: How do I add a second Y-axis? A: Use yaxis: right in the series config.

Q: How do I customize legend behavior? A: Legend is always interactive; at least one series remains visible.

All Options & Styles

Data Options

Option Type Default Description
sensor_id string - Entity ID from TimescaleDB
entities list - List of series objects
downsample number auto Downsample interval in seconds. Auto: ~80 points
y_margin number 5 Y-axis margin above/below values
height number 400 Chart height in pixels
nan_as_zero boolean false Treat NaN values as 0 in the series
gap_drop_to_zero boolean false When nan_as_zero is true, draw vertical drops to 0 over gaps
gap_drop_min_points number 2 Minimum consecutive missing points before dropping to 0
connect_gaps boolean false Connect gaps to keep a continuous line (ignored if gap_drop_to_zero is true)
extend_edge_gaps boolean false Extend first/last known value to chart edges
chart_type string line Chart type: line or bar
fill boolean true Enable area fill under line
line_color string rgb(75,192,192) Line color
line_width number 2 Line thickness
fill_color string rgba(75,192,192,0.2) Fill color under line
unit string '' Y-axis unit label
name string sensor_id Series name in legend
yaxis string left left or right (for separate scale)
type string line line or bar for this series
tooltip_label_text string friendly name Label used in tooltip and status text
show_bar_values boolean true Show value labels on bar charts (0-values stay hidden by default)
bar_value_position string inside Label position for bar values: inside or outside
bar_value_decimals number 2 Number of decimals shown in bar labels
bar_value_min_width_px number 28 Minimum bar width for horizontal label (else vertical)
bar_value_font_size number 11 Bar label font size
bar_value_text_color string bar_value_font_color Preferred bar label text color alias
bar_value_font_color string font_color Bar label text color
totals_decimals number bar_value_decimals Decimals used in totals boxes
show_total_box boolean true Show/hide this series in totals boxes row

Time Selection

Option Type Default Description
show_time_selector boolean true Show time range buttons
default_range string 24h Initial range
time_ranges list [1h,2h,3h,6h,12h,24h,48h,72h,custom] Which buttons to show
show_custom_button boolean true Show/hide custom range button
auto_refresh number 300 Auto-refresh interval in seconds
sync_group string unset Enable cross-card sync for cards in same group
sync_mode string both master, follower, both, off
sync_role string both Alias for sync_mode
time_mode string unset Use energy_calendar for energy calendar mode
energy_mode boolean false Alternative switch for energy calendar mode
energy_time_ranges list [today,month,year,week,years,custom] Energy selector options
energy_year number current year Initial energy selector year
energy_month number current month Initial energy selector month
energy_day number current day Initial energy selector day
energy_week number current ISO week Initial energy selector week
energy_bucket string 1h Bucket size in energy mode (m, h, d)
energy_week_start number 1 Week start day (0-6)
energy_years_count number 8 Number of years in years range
energy_years_offset number 0 Offset of years window
energy_downsample number auto Query downsample override in energy mode
energy_source_type string auto delta or cumulative
energy_cumulative_mode string last Cumulative handling mode
energy_handle_reset boolean true Handle counter reset behavior

Layout & Margins

Option Type Default Description
margin_top number 50 Top margin
margin_right number 60 Right margin
margin_bottom number 40 Bottom margin
margin_left number 50 Left margin

Axis Styling

Option Type Default Description
xaxis_title string Time X-axis title
yaxis_title string auto Left Y-axis title (set to NaN to hide)
yaxis_title_left string auto Left Y-axis title override
yaxis_title_right string auto Right Y-axis title override
yaxis_title_position string axis axis (default) or top to show titles above scales
axis_title_offset_y string 100px Vertical offset for axis titles
axis_title_offset_left string 20px Horizontal offset for left axis title
axis_title_offset_right string 40px Horizontal offset for right axis title
grid_color string rgba Grid line color
xaxis_tick_padding number 6 Space between grid and bottom tick labels
yaxis_tick_padding number 6 Space between grid and left tick labels

Button Styling

Option Type Default Description
selector_background_color string var(--card-background-color) Time selector background
button_background_color string var(--primary-background-color) Button background
button_border_color string var(--divider-color) Button border color
button_text_color string var(--primary-text-color) Button text color
button_active_color string var(--primary-color) Active button color
button_radius string 4px Button border radius
button_hover_color string var(--secondary-background-color) Button hover background
button_hover_text_color string var(--primary-text-color) Button hover text
button_active_text_color string white Button active text
select_background_color string button_background_color Energy select background
select_border_color string button_border_color Energy select border
select_text_color string button_text_color Energy select text color
select_active_background_color string button_active_color Active energy select background
select_active_border_color string button_active_color Active energy select border
select_active_text_color string button_active_text_color Active energy select text
select_option_background_color string select_background_color Energy dropdown option background
select_option_text_color string select_text_color Energy dropdown option text
select_label_color string button_text_color Energy selector label color
series_total_box_width string 108px Fixed width of each totals box

Custom Range Styling

Option Type Default Description
custom_range_background_color string var(--card-background-color) Custom range background
custom_range_border_color string var(--divider-color) Custom range top border
custom_range_text_color string var(--primary-text-color) Custom range label text
custom_range_label_size string 13px Custom range label size

Date Input Styling

Option Type Default Description
date_input_background_color string var(--primary-background-color) Input background
date_input_border_color string var(--divider-color) Input border
date_input_text_color string var(--primary-text-color) Input text
date_input_padding string 4px 8px Input padding
date_input_radius string 4px Input radius
date_input_size string 13px Input text size
date_input_accent_color string var(--primary-color) Input accent
date_input_scheme string dark Popup scheme
date_input_focus_color string rgba(3,169,244,0.4) Focus ring color
date_input_caret_color string var(--primary-text-color) Caret color
date_input_field_background_color string transparent Inner field background
date_picker_icon_filter string invert(0.9) Picker icon filter
date_picker_icon_opacity string 0.8 Picker icon opacity

Apply Button Styling

Option Type Default Description
apply_button_padding string 6px 16px Apply button padding
apply_button_background_color string var(--primary-color) Apply button background
apply_button_border_color string transparent Apply button border
apply_button_text_color string white Apply button text
apply_button_radius string 4px Apply button radius
apply_button_size string 13px Apply button text size
apply_button_hover_color string var(--primary-color) Apply button hover background
apply_button_hover_filter string brightness(1.05) Apply button hover filter

Status Text Styling

Option Type Default Description
show_status_text boolean true Show/hide status text line
status_text_color string var(--secondary-text-color) Status text color
status_text_size string 12px Status text size
status_text_padding string 8px 16px Status text padding
status_text_weight string normal Status text weight

Modebar Styling

Option Type Default Description
show_modebar boolean true Show Plotly modebar
modebar_bg_color string rgba(255,255,255,0.9) Modebar background
modebar_radius string 4px Modebar border radius
modebar_icon_color string var(--primary-text-color) Modebar icon color
modebar_icon_hover_color string var(--primary-color) Modebar icon hover color
modebar_icon_active_color string var(--primary-color) Modebar icon active color

Tooltip & Hover Styling

Option Type Default Description
tooltip_bg_color string rgba(248, 11, 248, 0.9) Tooltip background
tooltip_text_color string #ffffff Tooltip text color
tooltip_border_color string rgba(255,255,255,0.2) Tooltip border color
hover_line_color string rgba(120,120,120,0.8) Vertical hover line color

Download Options

Option Type Default Description
download_theme string dark Download theme: light or dark
download_format string svg Download format: png, svg, jpeg, webp
download_filename string timescale_chart Download filename
download_width number 1200 Download width in pixels
download_height number 600 Download height in pixels
download_scale number 2 Download scale (higher = better quality)

Time Selection

Option Type Default Description
show_time_selector boolean true Show time range buttons
default_range string 24h Initial range
time_ranges list [1h,2h,3h,6h,12h,24h,48h,72h,custom] Which buttons to show
show_custom_button boolean true Show/hide custom range button
auto_refresh number 300 Auto-refresh interval in seconds

Layout & Margins

Option Type Default Description
margin_top number 50 Top margin
margin_right number 60 Right margin
margin_bottom number 40 Bottom margin
margin_left number 50 Left margin

Axis Styling

Option Type Default Description
xaxis_title string Time X-axis title
yaxis_title string auto Left Y-axis title (set to NaN to hide)
yaxis_title_left string auto Left Y-axis title override
yaxis_title_right string auto Right Y-axis title override
axis_title_offset_y string 100px Vertical offset for axis titles
axis_title_offset_left string 20px Horizontal offset for left axis title
axis_title_offset_right string 40px Horizontal offset for right axis title
grid_color string rgba Grid line color

Chart Styling

Option Type Default Description
line_color string rgb(75,192,192) Line color
line_width number 2 Line thickness
fill_color string rgba(75,192,192,0.2) Fill color under line
fill boolean true Enable area fill under line
unit string '' Y-axis unit label

Button Styling

Option Type Default Description
selector_background_color string var(--card-background-color) Time selector background
button_background_color string var(--primary-background-color) Button background
button_border_color string var(--divider-color) Button border color
button_text_color string var(--primary-text-color) Button text color
button_active_color string var(--primary-color) Active button color
button_radius string 4px Button border radius
button_hover_color string var(--secondary-background-color) Button hover background
button_hover_text_color string var(--primary-text-color) Button hover text
button_active_text_color string white Button active text
select_background_color string button_background_color Energy select background
select_border_color string button_border_color Energy select border
select_text_color string button_text_color Energy select text color
select_active_background_color string button_active_color Active energy select background
select_active_border_color string button_active_color Active energy select border
select_active_text_color string button_active_text_color Active energy select text
select_option_background_color string select_background_color Energy dropdown option background
select_option_text_color string select_text_color Energy dropdown option text
select_label_color string button_text_color Energy selector label color
series_total_box_width string 108px Fixed width of each totals box

Custom Range Styling

Option Type Default Description
custom_range_background_color string var(--card-background-color) Custom range background
custom_range_border_color string var(--divider-color) Custom range top border
custom_range_text_color string var(--primary-text-color) Custom range label text
custom_range_label_size string 13px Custom range label size

Date Input Styling

Option Type Default Description
date_input_background_color string var(--primary-background-color) Input background
date_input_border_color string var(--divider-color) Input border
date_input_text_color string var(--primary-text-color) Input text
date_input_padding string 4px 8px Input padding
date_input_radius string 4px Input radius
date_input_size string 13px Input text size
date_input_accent_color string var(--primary-color) Input accent
date_input_scheme string dark Popup scheme
date_input_focus_color string rgba(3,169,244,0.4) Focus ring color
date_input_caret_color string var(--primary-text-color) Caret color
date_input_field_background_color string transparent Inner field background
date_picker_icon_filter string invert(0.9) Picker icon filter
date_picker_icon_opacity string 0.8 Picker icon opacity

Apply Button Styling

Option Type Default Description
apply_button_padding string 6px 16px Apply button padding
apply_button_background_color string var(--primary-color) Apply button background
apply_button_border_color string transparent Apply button border
apply_button_text_color string white Apply button text
apply_button_radius string 4px Apply button radius
apply_button_size string 13px Apply button text size
apply_button_hover_color string var(--primary-color) Apply button hover background
apply_button_hover_filter string brightness(1.05) Apply button hover filter

Status Text Styling

Option Type Default Description
show_status_text boolean true Show/hide status text line
status_text_color string var(--secondary-text-color) Status text color
status_text_size string 12px Status text size
status_text_padding string 8px 16px Status text padding
status_text_weight string normal Status text weight

Modebar Styling

Option Type Default Description
show_modebar boolean true Show Plotly modebar
modebar_bg_color string rgba(255,255,255,0.9) Modebar background
modebar_radius string 4px Modebar border radius
modebar_icon_color string var(--primary-text-color) Modebar icon color
modebar_icon_hover_color string var(--primary-color) Modebar icon hover color
modebar_icon_active_color string var(--primary-color) Modebar icon active color

Tooltip & Hover Styling

Option Type Default Description
tooltip_bg_color string rgba(248, 11, 248, 0.9) Tooltip background
tooltip_text_color string #ffffff Tooltip text color
tooltip_border_color string rgba(255,255,255,0.2) Tooltip border color
hover_line_color string rgba(120,120,120,0.8) Vertical hover line color

Download Options

Option Type Default Description
download_theme string dark Download theme: light or dark
download_format string svg Download format: png, svg, jpeg, webp
download_filename string timescale_chart Download filename
download_width number 1200 Download width in pixels
download_height number 600 Download height in pixels
download_scale number 2 Download scale (higher = better quality)

Clone this wiki locally