# History graph card

> The history graph card shows how the states of one or more entities changed over the last hours, as line charts for numbers and a timeline for everything else.

Source: https://contributors.home-assistant.io/design/dashboards/history-graph-card/

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 460px" data-props='{"config": {"type": "history-graph", "entities": ["sensor.living_room_temperature", "sensor.outdoor_temperature"]}}'></hui-card>
```

## Usage

The history graph card answers the question "what happened?". It shows the states of entities over a period of time, 24 hours by default. Unlike the small graph of the [sensor card](https://contributors.home-assistant.io/design/dashboards/sensor-card/), it has axes, a legend, and a tooltip with the exact value at any moment.

Use it to compare entities, like the temperature inside and outside, or to see when something happened, like when the front door opened. For a single number where only the trend matters, the [sensor card](https://contributors.home-assistant.io/design/dashboards/sensor-card/) takes less room. For long periods, like a month or a year, the statistics graph card fits better: it works from the hourly long-term statistics instead of every single state.

### Line charts and timelines

How the card draws an entity depends on its state.

- Entities with a numeric state and a unit, like temperatures, get a line chart. Entities that share a unit share a chart, so values that belong together sit on the same axis. Climate, humidifier, and water heater entities get a line chart too, with their current and target values.
- Everything else, like doors, lights, and locks, gets a timeline: a bar per entity, colored by state.

When you mix both kinds, the card shows the timeline and the line charts below each other. That works, but the card gets tall fast. Put entities that people compare in one card, and split the rest over more cards.

With `split_device_classes: true`, line charts are split by device class as well, so a temperature and a dew point that share a unit get a chart each.

### Time range

`hours_to_show` sets how far back the card goes. Large values make the card slower, especially for entities that change often. When the range is longer than the history Home Assistant keeps, the card fills the older part with long-term statistics, which are hourly averages.

### Axes

By default, the vertical axis follows the values. Set `min_y_axis` and `max_y_axis` for a fixed scale, like 0 to 100 for percentages, so small changes don't look dramatic. `fit_y_data` lets the axis grow beyond those bounds when the data needs it. `logarithmic_scale` helps when the values cover a very wide range.

### Content

- Give the card a `title` when it has more than one entity. The title links to the history panel with the same entities.
- Names default to the device and the entity, like **Thermostat** ▸ **Living room temperature**. Give an entity a shorter `name` when the context is clear.
- Set a `color` per entity only when the default colors make it hard to tell them apart, or when a color carries meaning.

## Configuration

- `entities` (list, required): the entities to show. Each is an entity ID, or a map with `entity`, and optionally `name` and `color`.
- `hours_to_show` (number): how many hours the card shows. Defaults to `24`.
- `title` (string): the title of the card.
- `show_names` (boolean): shows the names of the entities. Defaults to `true`.
- `logarithmic_scale` (boolean): uses a logarithmic vertical axis. Defaults to `false`.
- `min_y_axis` (number): the lower bound of the vertical axis.
- `max_y_axis` (number): the upper bound of the vertical axis.
- `fit_y_data` (boolean): lets the axis grow beyond the bounds to fit the data. Defaults to `false`.
- `split_device_classes` (boolean): splits line charts by device class, not only by unit. Defaults to `false`.
- `expand_legend` (boolean): shows all items of the legend from the start. Defaults to `false`.

```yaml
type: history-graph
title: "Temperature"
hours_to_show: 12
entities:
  - entity: sensor.living_room_temperature
    name: "Inside"
  - entity: sensor.outdoor_temperature
    name: "Outside"
```

## In code

The card lives in [`src/panels/lovelace/cards/hui-history-graph-card.ts`](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-history-graph-card.ts), and the element is `<hui-history-graph-card>`. It subscribes to the history of its entities, adds long-term statistics for the part outside the recorded history, and passes the result to `<state-history-charts>` in [`src/components/chart/`](https://github.com/home-assistant/frontend/tree/dev/src/components/chart). That component is shared with the history panel, so the card and the panel look the same.

In the sections view, the card takes the full width of a section and can shrink to half of it. Its height follows the content, unless the grid options set a number of rows.

[Source](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-history-graph-card.ts)