Documentation

Installation

HACS (Recommended)

Chronicle Card is in the HACS default store. One-click open:

1. Open HACS in your Home Assistant instance
2. Search for Chronicle Card and click Download
3. Go to Settings → Dashboards → Resources, click Add, and enter /hacsfiles/chronicle-card/chronicle-card.js as JavaScript Module
4. Restart Home Assistant

Manual Installation

1. Download chronicle-card.js from the latest release
2. Copy to /config/www/chronicle-card.js
3. Add the resource in Settings → Dashboards → Resources:
   URL: /local/chronicle-card.js, Type: JavaScript Module

Quick Start

Add a new card to any dashboard and paste the following minimal configuration:

Card Options

Top-level configuration options for the card.

Sources

Chronicle supports four source types. Each source feeds events into the unified timeline. You can combine any number and type of sources in a single card.

Calendar Source

Reads events from a Home Assistant calendar entity.

REST / WebSocket Source

Fetches events from a REST API endpoint or via Home Assistant WebSocket messages. Use field_map to map response fields to Chronicle's event schema.

REST Example

WebSocket Example (Frigate)

Field Map Keys

History Source

Converts entity state changes into timeline events. A single history source can watch multiple entities via the entities list, with per-entity overrides via entity_config. Chronicle reads the device_class attribute for smart human-readable translations, and automatically deduplicates repeated words in titles and descriptions (e.g. “Doorbell Motion Motion Cleared” becomes “Doorbell Motion Cleared”). You can attach Jinja2 templates for dynamic thumbnails and HA-native tap/hold actions to each event.

Custom State Map

Override the default state translations with a custom state_map:

State Filter

Use state_filter to only create events when the new state matches one of the listed values. For example, to log only when a motion sensor turns on (ignoring the “off” / cleared transition):

Device Class Translations

The following device classes are automatically translated when no state_map is provided:

History Source Options

Per-Entity Config (entity_config.<entity_id>)

Customize filtering, naming, and appearance for individual entities within a history source. Per-entity settings override source-level defaults, which override auto-detected device class defaults.

Static Source

Define events directly in YAML. Useful for reminders, scheduled tasks, or manually curated events.

Source Options (All Types)

These options are available on every source type.

Filters

Filter events by category, severity, source, entity, or free-text search. Inclusion filters narrow the timeline to only matching events; exclusion filters hide specific items while keeping everything else visible. The visual editor exposes these as a dedicated Filters section with a search field, comma-separated categories input, severity checkboxes (critical, warning, info, debug), source/entity dropdowns, and a nested Exclusions section mirroring the same options.

Grouping

Group nearby events together to reduce visual clutter. The grouping window uses a sliding comparison — each event is compared to the previous event in the group rather than the first, which produces more natural chaining of related events. Group summaries are context-aware: when all grouped events share the same label the summary uses that label (e.g. “7 cat events”), and when events are mixed it falls back to the source or entity name (e.g. “7 Frigate events”).

Per-source grouping override

Each source entry can declare its own grouping block. When set, that source's events are grouped in isolation (events from other sources won't mix into the same group), then merged back into the global timeline by timestamp. Sources without an override fall through to the card-level grouping config above, so existing setups are unchanged.

The visual editor exposes this as a Grouping Override expansion panel inside each source row. Leave any field blank to inherit the card-level value; the Clear override button removes the entire override.

Appearance

Fine-tune the visual style of the card.

Actions

Add action buttons to events. Actions can navigate, call services, or fire custom events.

Icon & Color Resolution

Chronicle resolves icons and colors through a 5-level chain. The first match wins.

1. color_map / icon_map — custom per-source overrides
2. default_color / default_icon — per-source fallback values
3. Fuzzy keyword inference — 150+ built-in rules that match event titles and categories
4. Category defaults — built-in icons for common categories
5. Global fallback — mdi:calendar-clock / #78909C

Keyword Match Examples

Override Example

Severity System

Chronicle supports four severity levels. Each event can have a severity set via the source default_severity, field_map, or static event config. Severity badges appear on events and can be restyled via appearance.severity_colors.

Layouts

Chronicle provides two layout modes:

• Vertical (default) — A scrollable timeline with a timeline line and event nodes. Best for detailed event inspection.
• Horizontal — A ribbon layout for compact display (e.g., camera events as a horizontal strip). Best for dashboards with limited vertical space.

Toggle between them at runtime with show_layout_toggle: true, or set a fixed layout:

Log Event Blueprint

A ready-to-use Home Assistant automation blueprint is included at blueprints/chronicle_log_event.yaml. It logs entity state changes to a calendar entity, which Chronicle then reads as timeline events.

Blueprint Inputs

Usage Example

Camera Detection Snapshots Blueprint

For cameras that expose AI detections as binary sensors (Reolink, Amcrest, ONVIF, etc.), this blueprint captures a snapshot on each detection and saves it with a timestamp-based filename. Chronicle Card's image_template then matches each timeline event to its snapshot automatically.

Prerequisites

1. Input Number Helper — Create via Settings → Devices & Services → Helpers → Add Helper → Number. Name it chronicle_snapshot_retention, min 1, max 30, step 1, initial 7, unit "days". Alternatively, add to configuration.yaml:
   input_number: chronicle_snapshot_retention: name: Chronicle Snapshot Retention icon: mdi:calendar-clock min: 1 max: 30 step: 1 initial: 7 unit_of_measurement: days
2. Shell Command — Add to configuration.yaml:
   shell_command: clean_chronicle_snapshots: "find /config/www/snapshots -type f -name '*_????????_??????.jpg' -mtime +{{ states('input_number.chronicle_snapshot_retention') | int(7) }} -delete"
3. Snapshot directory — Create /config/www/snapshots/ if it doesn't exist.

Card Configuration

Add image_template to your history sources to match events to their snapshots:

Both the blueprint and image_template normalize through as_timestamp (epoch seconds) then timestamp_custom (HA's local timezone), ensuring filenames match regardless of timezone configuration.

Supported Cameras

• Reolink — person, vehicle, pet, face, package, visitor (doorbell)
• Amcrest / Dahua — motion, person, vehicle
• Generic ONVIF — motion, person (if supported by firmware)
• Any camera with binary_sensor detection entities + a camera entity for snapshots

Does not replace Frigate — Frigate has its own event system with built-in thumbnails. Use the REST adapter with media_url_template for Frigate instead.

Example: LLM Vision Integration

Pair the LLM Vision integration with image_template so each timeline event can show its analyzed snapshot. The automation saves the frame to a predictable path (timestamp-based) and the card's template matches each event to its snapshot.

1. Save the snapshot in your automation

2. Match the snapshot in Chronicle

Use the same timestamp format in image_template so each event resolves to its own saved frame:

The LLM caption ends up in input_text.doorbell_last_caption and can be surfaced via a separate static or REST source if you want it on the timeline alongside the snapshot. The Camera Snapshots blueprint above can replace step 1 entirely if you only need the snapshot without analysis.

Example: Frigate Camera Events

Display Frigate NVR detections with snapshot thumbnails in a timeline.

Example: Multi-Source Home Timeline

Combine calendar events, camera detections, and door sensor history in one view.

Example: Compact Security Log

A compact, filtered view showing only security-relevant events.

Example: Horizontal Camera Ribbon

Show Frigate events as a horizontal scrolling ribbon with thumbnails.

Example: Logging Automations

Use Home Assistant automations to write events into a calendar entity that Chronicle reads. This approach lets you log any state change, webhook, or trigger as a timeline event.

Localization

Chronicle auto-detects the language from your Home Assistant locale. Override it with the language card option.

Development

To build and develop Chronicle Card locally:

Output is written to dist/chronicle-card.js. Copy it to your Home Assistant /config/www/ directory during development.