# Chart Examples

This guide showcases the different chart configurations available through the `tibber_prices.get_apexcharts_yaml` action.

> **Quick Start:** Call the action with your desired parameters, copy the generated YAML, and paste it into your Lovelace dashboard!

:::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::

:::info Finding your Entry ID (`entry_id`)
Every example below contains `entry_id: YOUR_CONFIG_ENTRY_ID`. This value identifies which Tibber home (integration instance) the action targets.

**In the Action UI (Developer Tools → Actions or the automation editor):** The `entry_id` field is a **dropdown** — just select your Tibber home and HA fills in the correct ID automatically.

**In YAML:** Go to **Settings → Devices & Services**, find the **Tibber Prices** card, open the **⋮** (three-dot) menu, and choose **"Copy Config Entry ID"**. Paste the copied value in place of `YOUR_CONFIG_ENTRY_ID`.
:::

## Overview

The integration can generate 4 different chart modes, each optimized for specific use cases:

| Mode | Description | Best For | Dependencies |
|------|-------------|----------|--------------|
| **Today** | Static 24h view of today's prices | Quick daily overview | ApexCharts Card |
| **Tomorrow** | Static 24h view of tomorrow's prices | Planning tomorrow | ApexCharts Card |
| **Rolling Window** | Dynamic 48h view (today+tomorrow or yesterday+today) | Always-current overview | ApexCharts + Config Template Card |
| **Rolling Window Auto-Zoom** | Dynamic view that zooms in as day progresses | Real-time focus on remaining day | ApexCharts + Config Template Card |

**Screenshots available for:**
- ✅ Today (static) - Representative of all fixed day views
- ✅ Rolling Window - Shows dynamic Y-axis scaling
- ✅ Rolling Window Auto-Zoom - Shows progressive zoom effect

## All Chart Modes

### 1. Today's Prices (Static)

**When to use:** Simple daily price overview, no dynamic updates needed.

**Dependencies:** ApexCharts Card only

**Generate:**
<details>
<summary>Show YAML: Today's Prices (Static)</summary>

```yaml
service: tibber_prices.get_apexcharts_yaml
data:
    entry_id: YOUR_CONFIG_ENTRY_ID
    day: today
    level_type: rating_level
    highlight_best_price: true
```

</details>

**Screenshot:**

![Today's Prices - Static 24h View](/img/charts/today.jpg)

**Key Features:**
- ✅ Color-coded price levels (LOW, NORMAL, HIGH)
- ✅ Best price period highlights (vertical bands)
- ✅ Static 24-hour view (00:00 - 23:59)
- ✅ Works with ApexCharts Card alone

**Note:** Tomorrow view (`day: tomorrow`) works identically to Today view, just showing tomorrow's data. All fixed day views (yesterday/today/tomorrow) use the same visualization approach.

---

### 2. Rolling 48h Window (Dynamic)

**When to use:** Always-current view that automatically switches between yesterday+today and today+tomorrow.

**Dependencies:** ApexCharts Card + Config Template Card

**Generate:**
<details>
<summary>Show YAML: Rolling 48h Window</summary>

```yaml
service: tibber_prices.get_apexcharts_yaml
data:
    entry_id: YOUR_CONFIG_ENTRY_ID
    # Omit 'day' for rolling window
    level_type: rating_level
    highlight_best_price: true
```

  </details>

**Screenshot:**

![Rolling 48h Window with Dynamic Y-Axis Scaling](/img/charts/rolling-window.jpg)

**Key Features:**
- ✅ **Dynamic Y-axis scaling** via `chart_metadata` sensor
- ✅ Automatic data selection: today+tomorrow (when available) or yesterday+today
- ✅ Always shows 48 hours of data
- ✅ Updates automatically when tomorrow's data arrives
- ✅ Color gradients for visual appeal

**How it works:**
- Before ~13:00: Shows yesterday + today
- After ~13:00: Shows today + tomorrow
- Y-axis automatically adjusts to data range for optimal visualization

---

### 3. Rolling Window Auto-Zoom (Dynamic)

**When to use:** Real-time focus on remaining day - progressively zooms in as day advances.

**Dependencies:** ApexCharts Card + Config Template Card

**Generate:**
<details>
<summary>Show YAML: Rolling Auto-Zoom</summary>

```yaml
service: tibber_prices.get_apexcharts_yaml
data:
    entry_id: YOUR_CONFIG_ENTRY_ID
    day: rolling_window_autozoom
    level_type: rating_level
    highlight_best_price: true
```

  </details>

**Screenshot:**

![Rolling Window Auto-Zoom - Progressive Zoom Effect](/img/charts/rolling-window-autozoom.jpg)

**Key Features:**
- ✅ **Progressive zoom:** Graph span decreases every 15 minutes
- ✅ **Dynamic Y-axis scaling** via `chart_metadata` sensor
- ✅ Always shows: 2 hours lookback + remaining time until midnight
- ✅ Perfect for real-time price monitoring
- ✅ Example: At 18:00, shows 16:00 → 00:00 (8h window)

**How it works:**
- 00:00: Shows full 48h window (same as rolling window)
- 06:00: Shows 04:00 → midnight (20h window)
- 12:00: Shows 10:00 → midnight (14h window)
- 18:00: Shows 16:00 → midnight (8h window)
- 23:45: Shows 21:45 → midnight (2.25h window)

This creates a "zooming in" effect that focuses on the most relevant remaining time.

---

## Comparison: Level Type Options

### Rating Level (3 series)

Based on **your personal price thresholds** (configured in Options Flow):

- **LOW** (Green): Below your "cheap" threshold
- **NORMAL** (Blue): Between thresholds
- **HIGH** (Red): Above your "expensive" threshold

**Best for:** Personal decision-making based on your budget

### Level (5 series)

Based on **absolute price ranges** (calculated from daily min/max):

- **VERY_CHEAP** (Dark Green): Bottom 20%
- **CHEAP** (Light Green): 20-40%
- **NORMAL** (Blue): 40-60%
- **EXPENSIVE** (Orange): 60-80%
- **VERY_EXPENSIVE** (Red): Top 20%

**Best for:** Objective price distribution visualization

---

## Dynamic Y-Axis Scaling

Rolling window modes (2 & 3) automatically integrate with the `chart_metadata` sensor for optimal visualization:

**Without chart_metadata sensor (disabled):**
<details>
<summary>Show chart illustration: Without Chart Metadata</summary>

```
┌─────────────────────┐
│                     │ ← Lots of empty space
│      ___            │
│  ___/   \___        │
│_/           \_      │
├─────────────────────┤
0              100 ct
```

</details>

**With chart_metadata sensor (enabled):**
<details>
<summary>Show chart illustration: With Chart Metadata</summary>

```
┌─────────────────────┐
│      ___            │ ← Y-axis fitted to data
│  ___/   \___        │
│_/           \_      │
├─────────────────────┤
18             28 ct   ← Optimal range
```

</details>

**Requirements:**

- ✅ The `sensor.<home_name>_chart_metadata` must be **enabled** (it's enabled by default!)
- ✅ That's it! The generated YAML automatically uses the sensor for dynamic scaling

**Important:** Do NOT disable the `chart_metadata` sensor if you want optimal Y-axis scaling in rolling window modes!

**Note:** Fixed day views (`today`, `tomorrow`) use ApexCharts' built-in auto-scaling and don't require the metadata sensor.

---

## Best Price Period Highlights

When `highlight_best_price: true`, vertical bands overlay the chart showing detected best price periods:

**Example:**
<details>
<summary>Show chart illustration: Best Price Period Highlights</summary>

```
Price
  │
30│           ┌─────────┐  Normal prices
  │           │         │
25│     ▓▓▓▓▓▓│         │  ← Best price period (shaded)
  │     ▓▓▓▓▓▓│         │
20│─────▓▓▓▓▓▓│─────────│
  │     ▓▓▓▓▓▓
  └─────────────────────── Time
       06:00  12:00  18:00
```

</details>

**Features:**
- Automatic detection based on your configuration (see [Period Calculation Guide](period-calculation.md))
- Tooltip shows "Best Price Period" label
- Only appears when periods are configured and detected
- Can be disabled with `highlight_best_price: false`

---

## Prerequisites

### Required for All Modes

- **[ApexCharts Card](https://github.com/RomRider/apexcharts-card)**: Core visualization library
<details>
<summary>Show shell command: Prerequisite for All Modes</summary>

  ```bash
  # Install via HACS
  HACS → Frontend → Search "ApexCharts Card" → Download
  ```

</details>

### Required for Rolling Window Modes Only

- **[Config Template Card](https://github.com/iantrich/config-template-card)**: Enables dynamic configuration
<details>
<summary>Show shell command: Rolling Window Prerequisite</summary>

  ```bash
  # Install via HACS
  HACS → Frontend → Search "Config Template Card" → Download
  ```

</details>

**Note:** Fixed day views (`today`, `tomorrow`) work with ApexCharts Card alone!

---

## Tips & Tricks

### Customizing Colors

Edit the `colors` array in the generated YAML:

<details>
<summary>Show YAML: Custom Color Palette</summary>

```yaml
apex_config:
    colors:
        - "#00FF00"  # Change LOW/VERY_CHEAP color
        - "#0000FF"  # Change NORMAL color
        - "#FF0000"  # Change HIGH/VERY_EXPENSIVE color
```

</details>

### Changing Chart Height

Add to the card configuration:

<details>
<summary>Show YAML: Custom Chart Height</summary>

```yaml
type: custom:apexcharts-card
graph_span: 48h
header:
    show: true
    title: My Custom Title
apex_config:
    chart:
        height: 400  # Adjust height in pixels
```

</details>

### Combining with Other Cards

Wrap in a vertical stack for dashboard integration:

<details>
<summary>Show YAML: Vertical Stack Integration</summary>

```yaml
type: vertical-stack
cards:
    - type: entity
      entity: sensor.<home_name>_current_electricity_price
    - type: custom:apexcharts-card
      # ... generated chart config
```

</details>

---

## Next Steps

- **[Chart Actions Guide](chart-actions.md)**: Complete documentation of `get_apexcharts_yaml` parameters
- **[Chart Metadata Sensor](sensors-overview.md#chart-metadata)**: Learn about dynamic Y-axis scaling
- **[Period Calculation Guide](period-calculation.md)**: Configure best price period detection

---

## Screenshots

### Gallery

1. **Today View (Static)** - Representative of all fixed day views (yesterday/today/tomorrow)

   ![Today View](/img/charts/today.jpg)

2. **Rolling Window (Dynamic)** - Shows dynamic Y-axis scaling and 48h window

   ![Rolling Window](/img/charts/rolling-window.jpg)

3. **Rolling Window Auto-Zoom (Dynamic)** - Shows progressive zoom effect

   ![Rolling Window Auto-Zoom](/img/charts/rolling-window-autozoom.jpg)

**Note:** Tomorrow view is visually identical to Today view (same chart type, just different data).
