HomeRiz/hats

The Interactive Visual Designer, Community Store, Live Lovelace Sandbox, and Generator for Home Assistant Themes

Installation • Features • Environment Doctor • Configuration • Development

HATS (Home Assistant Theme Store) is an all-in-one Home Assistant App and visual theme studio designed to simplify theme discovery, visual customization, and environment configuration.

Operating seamlessly through Home Assistant Ingress or as a dedicated full-window Web UI, HATS connects directly to your Home Assistant instance to inspect prerequisites, auto-configure theme directories, download companion card dependencies via HACS, and apply custom glassmorphism themes with zero manual YAML editing required.

• 🎨 Visual Theme Designer: Real-time CSS and YAML generator with color pickers, specular highlights, border glows, ambient lighting, and corner radius sliders (8px–48px).
• 🔬 Live Lovelace Sandbox: Interactive dashboard preview featuring simulated Mushroom cards, climate sliders, weather widgets, media controls, and status chips.
• 🩺 HA Environment & Prerequisites Doctor:
  • Live inspection of configuration.yaml for theme directives (themes: !include_dir_merge_named themes).
  • Automatic detection of lovelace-card-mod on disk (/config/www/community/lovelace-card-mod).
  • Dynamic extraction of live hacstag version identifiers directly from HA storage.
  • 1-Click Auto-Fix: Automatically backs up and injects missing theme directives and extra_module_url references.
• 📦 1-Click Direct Theme Installer: Writes generated theme definitions directly to /config/themes/ and automatically triggers Home Assistant's frontend.reload_themes service.
• 🖼️ Artwork & Background Studio: Upload custom wallpapers (PNG, JPG, WebP), perform automatic 16:9 center crops, and save assets directly to /config/www/hats/backgrounds/.
• 🌐 Pop-Out Fullscreen Mode: Launch HATS in a full dedicated browser tab (↗) through Ingress. HATS is reachable only through Home Assistant Ingress (admin users); it publishes no host port and refuses direct network access.
• 🚀 In-App GitHub Theme Submission: Validate, package, and generate YAML for custom themes with one-click links to propose additions to the official repository.

1. In Home Assistant, go to Settings → Apps and click Install app to open the App store.
2. Click the top-right menu (⋮) and select Repositories.
3. Add the repository URL:

   https://github.com/HomeRiz/hats
   

4. Locate HATS - Home Assistant Theme Store in the store list and click Install.
5. Enable Show in sidebar and click Start.
6. Open HATS from your Home Assistant sidebar! 🎩

Modern Home Assistant themes (such as those in the HATS Signature Collection) require two core configuration elements: the themes merge directory directive and the lovelace-card-mod custom module registration.

In Home Assistant's configuration.yaml, the root frontend: key must only appear once. Both elements must be merged together under this single frontend: block:

frontend:
  themes: !include_dir_merge_named themes
  extra_module_url:
    - /hacsfiles/lovelace-card-mod/card-mod.js?hacstag=...

• Missing Plugin: HATS displays a direct "Install via HACS" button opening http://<ha-host>:8123/hacs/repository/190927524.
• Plugin Detected on Disk: The HA Setup badge in the navbar pulses amber with an alert.
• 1-Click Auto-Fix: Clicking Auto-Fix YAML Bridge reads the exact hacstag from your HA storage, creates a safety backup (configuration.yaml.hats_bak_<timestamp>), and injects the required configuration automatically.

The app works out-of-the-box with default options, but can be customized in the Configuration tab:

themes_directory: "/config/themes"
backgrounds_directory: "/config/www/hats/backgrounds"
auto_reload_themes: true

HATS is packaged as a Home Assistant Ingress App built from a multi-stage Docker image:

• Dockerfile: Builds the React + TypeScript single-page application and bundles it with a lightweight Express backend running on Node 20.
• run.sh: The mandatory container startup entrypoint. When Home Assistant Supervisor starts the container:
  • I. Ensures /config/themes exists on the host filesystem.
  • II. Ensures /config/www/hats/backgrounds exists on the host filesystem.
  • III. Launches the Ingress server (exec node server/index.js) on port 4287.
• config.yaml: Home Assistant app manifest specifying the Ingress route, permissions (Home Assistant API access to reload themes), the /config mapping, options, and architecture compatibility.
• repository.yaml: Home Assistant app repository descriptor.

For local UI development without a full Home Assistant supervisor:

# Clone the repository
git clone https://github.com/HomeRiz/hats.git
cd hats

# Install dependencies
npm install

# Start Vite development server
npm run dev

Open http://localhost:4287 in your browser.

Distributed under the GNU General Public License v3.0 (GPL-3.0). The license text is the unmodified GPLv3. See LICENSE. Copyright (C) 2026 HomeRiz and HATS Contributors. The project's intent is to stay free and community-driven; the GPL itself guarantees that derivative works stay open.