Chronicle Card Documentation

Installation

HACS Custom Repo (Recommended)

HACS Default store listing is pending. For now, install as a custom repository:

Open HACS in your Home Assistant instance
Click the three-dot menu (top right) → Custom repositories
Paste https://github.com/KadenThomp36/chronicle-card and select Dashboard as the category
Click Add, then find Chronicle Card and click Download
Go to Settings → Dashboards → Resources, click Add, and enter /hacsfiles/chronicle-card/chronicle-card.js as JavaScript Module
Restart Home Assistant

Manual Installation

Download chronicle-card.js from the latest release
Copy to /config/www/chronicle-card.js
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:

yaml

type: custom:chronicle-card
title: Home Timeline
sources:
  - type: calendar
    entity: calendar.home_events

Card Options

Top-level configuration options for the card.

Option	Type	Default	Description
`type`	string	Required	Must be `custom:chronicle-card`
`title`	string	`""`	Card title displayed in the header
`layout`	string	`vertical`	`vertical` or `horizontal`
`show_layout_toggle`	boolean	`true`	Show button to switch layouts
`max_events`	number	`50`	Maximum events to display
`days_back`	number	`7`	How many days of history to fetch
`time_format`	string	`24h`	`12h` or `24h`
`language`	string	`auto`	Override language (`en`, `de`, `fr`, `es`, `it`, `pt`, `nl`, `sv`)
`show_header`	boolean	`true`	Show the card header
`sources`	list	Required	Array of source configurations
`filters`	object	`{}`	Filter configuration
`grouping`	object	`{}`	Grouping configuration
`appearance`	object	`{}`	Appearance configuration

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.

yaml

sources:
  - type: calendar
    entity: calendar.home_events
    name: Home Events
    default_icon: mdi:calendar
    default_color: "#4CAF50"
    default_severity: info

Option	Type	Description
`entity`	string	Calendar entity ID

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

yaml

sources:
  - type: rest
    url: /api/some_integration/events
    name: My Events
    response_path: data.events
    field_map:
      id: uid
      title: name
      start: timestamp
      description: details
      mediaUrl: image_url
      category: type
    poll_interval: 60

WebSocket Example (Frigate)

yaml

sources:
  - type: rest
    name: Frigate Events
    ws_params:
      type: frigate/events/get
      limit: 50
    field_map:
      id: id
      title: label
      start: start_time
      category: label
      entityId: camera
    media_url_template: /api/frigate/notifications/{id}/snapshot.jpg

Option	Type	Description
`url`	string	REST API endpoint URL
`ws_params`	object	WebSocket message parameters (alternative to `url`)
`response_path`	string	Dot-notation path to the events array in the response
`field_map`	object	Maps response fields to Chronicle event fields
`media_url_template`	string	Template for media URLs with `{field}` placeholders
`poll_interval`	number	Polling interval in seconds

Field Map Keys

Key	Description
`id`	Unique event identifier
`title`	Event title / summary
`description`	Event description
`start`	Start time (ISO string or Unix timestamp)
`end`	End time
`mediaUrl`	Direct URL to media (image/thumbnail)
`mediaContentId`	HA media content ID
`icon`	MDI icon override
`color`	Color override
`category`	Event category for grouping / filtering
`label`	Display label
`severity`	Severity level
`entityId`	Associated entity ID
`entityName`	Associated entity name

History Source

Converts entity state changes into timeline events. Each history source watches a single entity — add one source per entity you want to track. Setting name on a history source overrides the entity's friendly_name in event titles. 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”).

yaml

sources:
  - type: history
    entity: binary_sensor.front_door
    name: Front Door
    default_severity: warning
  - type: history
    entity: lock.front_door_lock
    name: Front Door Lock
    default_severity: warning
  - type: history
    entity: alarm_control_panel.home
    name: Alarm Panel
    default_severity: warning

Custom State Map

Override the default state translations with a custom state_map:

yaml

sources:
  - type: history
    entity: binary_sensor.garage_tilt
    name: Garage
    state_map:
      "on": "Garage Opened"
      "off": "Garage Closed"

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):

yaml

sources:
  - type: history
    entity: binary_sensor.hallway_motion
    name: Hallway Motion
    state_filter:
      - "on"

Device Class Translations

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

Device Class	On State	Off State
door / opening / window	Opened	Closed
motion	Motion Detected	Motion Cleared
lock	Unlocked	Locked
smoke	Smoke Detected	Clear
moisture	Wet	Dry
occupancy	Occupied	Unoccupied
presence	Present	Away
vibration	Vibration	Still
connectivity	Connected	Disconnected
battery	Low	Normal

History Source Options

Option	Type	Description
`entity`	string	Entity ID to track (one entity per history source)
`state_filter`	string[]	Only create events when the new state matches a value in this list. E.g. `["on"]` to ignore “off” transitions.
`state_map`	object	Map of state values to custom display strings

Static Source

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

yaml

sources:
  - type: static
    name: Reminders
    events:
      - title: Change HVAC Filter
        start: "2025-04-01T10:00:00"
        icon: mdi:air-filter
        color: "#FF9800"
        severity: info
        category: maintenance

Source Options (All Types)

These options are available on every source type.

Option	Type	Description
`type`	string	Source type: `calendar`, `rest`, `history`, or `static`
`name`	string	Display name for the source
`default_icon`	string	Fallback MDI icon for events from this source
`default_color`	string	Fallback color for events from this source
`default_severity`	string	Fallback severity level (`critical`, `warning`, `info`, `debug`)
`icon_map`	object	Map of category/keyword to MDI icon
`color_map`	object	Map of category/keyword to color
`actions`	list	Action buttons for events from this source

Filters

Filter events by category, severity, source, entity, or free-text search. The visual editor exposes these as a dedicated Filters section with a search field, comma-separated categories input, severity checkboxes (critical, warning, info, debug), and source/entity dropdowns.

yaml

filters:
  categories:
    - person
    - vehicle
  severities:
    - critical
    - warning
  sources:
    - Frigate Events
  entities:
    - binary_sensor.front_door
  search: "front door"

Option	Type	Description
`categories`	list	Only show events matching these categories
`severities`	list	Only show events matching these severity levels
`sources`	list	Only show events from these source names
`entities`	list	Only show events from these entity IDs
`search`	string	Free-text search across event titles and descriptions

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”).

yaml

grouping:
  enabled: true
  window_seconds: 120
  min_group_size: 3
  group_by: category

Option	Type	Default	Description
`enabled`	boolean	`false`	Enable event grouping
`window_seconds`	number	`120`	Sliding time window (in seconds) — each event is compared to the previous event in the group
`min_group_size`	number	`3`	Minimum number of events to form a group
`group_by`	string	`category`	`category`, `source`, `entity`, or `none`

Appearance

Fine-tune the visual style of the card.

yaml

appearance:
  card_height: 400px
  compact: false
  show_images: true
  show_icons: true
  show_severity_badge: true
  show_source_badge: false
  animate_new_events: true
  severity_colors:
    critical: "#D32F2F"
    warning: "#FF9800"
    info: "#2196F3"
    debug: "#9E9E9E"

Option	Type	Default	Description
`card_height`	string	`400px`	Fixed height of the card body
`compact`	boolean	`false`	Use compact event rows
`show_images`	boolean	`true`	Show event thumbnails
`show_icons`	boolean	`true`	Show event icons
`show_severity_badge`	boolean	`true`	Show severity labels on events
`show_source_badge`	boolean	`false`	Show source name badge on events
`animate_new_events`	boolean	`true`	Animate new events as they arrive
`severity_colors`	object	(built-in)	Override severity level colors

Actions

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

yaml

sources:
  - type: calendar
    entity: calendar.cameras
    actions:
      - label: View Camera
        icon: mdi:cctv
        type: navigate
        url: /lovelace/cameras
      - label: Dismiss
        icon: mdi:close
        type: service
        service: input_boolean.turn_off
        target:
          entity_id: input_boolean.alert_active
      - label: Trigger Alarm
        icon: mdi:alarm-light
        type: fire-event
        eventType: custom_alarm
        eventData:
          zone: front_yard

Option	Type	Description
`label`	string	Button label text
`icon`	string	MDI icon for the button
`type`	string	Action type: `service`, `navigate`, or `fire-event`
`service`	string	Service to call (for `service` type)
`serviceData`	object	Additional data for the service call
`target`	object	Target entity/device/area for the service call
`url`	string	URL to navigate to (for `navigate` type)
`eventType`	string	Custom event type (for `fire-event` type)
`eventData`	object	Data payload for the custom event

Icon & Color Resolution

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

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

Keyword Match Examples

Keywords	Icon	Color
cat, kitten, feline	`mdi:cat`	`#7f41eb`
dog, puppy, canine	`mdi:dog`	`#8D6E63`
person, visitor	`mdi:walk`	`#FF9800`
car, truck, vehicle	`mdi:car`	`#2196F3`
package, delivery	`mdi:package-variant-closed`	`#795548`
alarm, alert	`mdi:alarm-light`	`#F44336`
door, gate	`mdi:door`	`#795548`
motion	`mdi:motion-sensor`	`#9C27B0`
camera, cctv	`mdi:cctv`	`#FF5722`
light, lamp	`mdi:lightbulb`	`#FFC107`
temperature	`mdi:thermostat`	`#00BCD4`

Override Example

yaml

sources:
  - type: rest
    url: /api/my/events
    icon_map:
      garage: mdi:garage
      backyard: mdi:tree
    color_map:
      garage: "#795548"
      backyard: "#4CAF50"

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.

Level	Default Color	Use Case
Critical	`#D32F2F`	Alarm triggers, smoke detection, security breaches
Warning	`#FF9800`	Person detected, door opened, unusual activity
Info	`#2196F3`	Calendar events, routine activity, status changes
Debug	`#9E9E9E`	Low-priority logs, diagnostic data

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:

yaml

type: custom:chronicle-card
layout: horizontal
show_layout_toggle: false

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

Input	Description
Trigger Entity	The entity to watch for state changes
Trigger State (optional)	Only log when entity enters this specific state
Target Calendar	Calendar entity where events are written
Event Title	Template-supported title (default: friendly name + state)
Event Description	Template-supported description body
Event Duration	Duration in minutes
Additional Condition	Optional extra condition to gate logging

Usage Example

yaml

automation:
  - alias: Log Front Door Activity
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door
        to: "on"
    action:
      - service: calendar.create_event
        target:
          entity_id: calendar.home_timeline
        data:
          summary: "Front door opened"
          description: "Door sensor triggered"
          start_date_time: "{{ now().isoformat() }}"
          end_date_time: "{{ (now() + timedelta(minutes=1)).isoformat() }}"

Import the blueprint directly: Import Blueprint

Example: Frigate Camera Events

Display Frigate NVR detections with snapshot thumbnails in a timeline.

yaml

type: custom:chronicle-card
title: Camera Events
sources:
  - type: rest
    name: Frigate Events
    ws_params:
      type: frigate/events/get
      limit: 50
    field_map:
      id: id
      title: label
      start: start_time
      end: end_time
      category: label
      entityId: camera
    media_url_template: /api/frigate/notifications/{id}/snapshot.jpg
    default_severity: warning

Example: Multi-Source Home Timeline

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

yaml

type: custom:chronicle-card
title: Home Timeline
days_back: 7
max_events: 100
sources:
  - type: calendar
    entity: calendar.home_events
    name: Calendar
    default_icon: mdi:calendar
    default_color: "#4CAF50"
    default_severity: info
  - type: rest
    name: Frigate
    ws_params:
      type: frigate/events/get
      limit: 50
    field_map:
      id: id
      title: label
      start: start_time
      category: label
      entityId: camera
    media_url_template: /api/frigate/notifications/{id}/snapshot.jpg
    default_severity: warning
  - type: history
    entity: binary_sensor.front_door
    name: Front Door
    default_severity: warning
  - type: history
    entity: binary_sensor.back_door
    name: Back Door
    default_severity: warning
  - type: history
    entity: lock.front_door_lock
    name: Front Door Lock
    default_severity: warning

Example: Compact Security Log

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

yaml

type: custom:chronicle-card
title: Security Log
sources:
  - type: history
    entity: binary_sensor.front_door
    name: Front Door
    default_severity: warning
  - type: history
    entity: binary_sensor.back_door
    name: Back Door
    default_severity: warning
  - type: history
    entity: binary_sensor.garage_door
    name: Garage Door
    default_severity: warning
  - type: history
    entity: lock.front_door_lock
    name: Front Door Lock
    default_severity: warning
  - type: history
    entity: alarm_control_panel.home
    name: Alarm Panel
    default_severity: warning
appearance:
  compact: true
  show_images: false
filters:
  severities:
    - critical
    - warning

Example: Horizontal Camera Ribbon

Show Frigate events as a horizontal scrolling ribbon with thumbnails.

yaml

type: custom:chronicle-card
title: Camera Ribbon
layout: horizontal
show_layout_toggle: false
sources:
  - type: rest
    name: Frigate
    ws_params:
      type: frigate/events/get
      limit: 20
    field_map:
      id: id
      title: label
      start: start_time
      category: label
      entityId: camera
    media_url_template: /api/frigate/notifications/{id}/snapshot.jpg

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.

yaml

# Automation that logs motion events to a calendar
automation:
  - alias: Log Motion to Timeline
    trigger:
      - platform: state
        entity_id: binary_sensor.hallway_motion
        to: "on"
    action:
      - service: calendar.create_event
        target:
          entity_id: calendar.home_timeline
        data:
          summary: "Motion detected in hallway"
          description: "Hallway motion sensor triggered"
          start_date_time: "{{ now().isoformat() }}"
          end_date_time: "{{ (now() + timedelta(minutes=1)).isoformat() }}"

# Then read it with Chronicle
type: custom:chronicle-card
title: Activity Log
sources:
  - type: calendar
    entity: calendar.home_timeline

Localization

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

Code	Language
`en`	English
`de`	German
`fr`	French
`es`	Spanish
`it`	Italian
`pt`	Portuguese
`nl`	Dutch
`sv`	Swedish

yaml

type: custom:chronicle-card
language: de

Development

To build and develop Chronicle Card locally:

bash

npm install
npm run build
npm run watch

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