🧭 Custom Sidebar & Header for Home Assistant

Supportami / Support Me

Se ti piace il mio lavoro e vuoi che continui nello sviluppo delle card, puoi offrirmi un caffè.
If you like my work and want me to continue developing the cards, you can buy me a coffee.

Non dimenticare di seguirmi sui social:
Don't forget to follow me on social media:

🧭 Custom Sidebar & Header for Home Assistant

🇮🇹 Italiano

Header Flip Mode

Header Push Mode

📸 Screenshots

A fully‑customisable Header + Sidebar layout system for Home Assistant, designed to be modern, flexible and responsive — while keeping full compatibility with Lovelace dashboards.

⭐ Main Features

Responsive sidebar width (mobile / tablet / desktop)
Sticky / glass‑style header
4 menu styles (list / wide / buttons / grid)
Conditional menu items
Per‑item colors and icons
Optional hiding of default HA sidebar + top bar
Template area for greetings / custom HTML
Supports any Lovelace card inside header & sidebar
Works with kiosk‑mode setups
Safe — does not hack core Lovelace layout
🆕 Built-in graphical editor — configure Sidebar & Header without editing YAML manually

🖊️ Graphical Editor (Admin only)

Administrators have access to a built-in visual editor to configure Sidebar and Header without touching the YAML file.

How to open it

Two ways:

Toolbar button — a dashboard-edit icon (🖊) appears in the top-right toolbar of HA when you are logged in as admin. Click it to open the editor panel.
Gear icon in the sidebar — a small ⚙ icon at the bottom of the sidebar (visible only to admins) also opens the editor.

Editor tabs

Tab	Description
Sidebar	Configure sidebar width, clock, date format, menu style, menu items, bottomCard and custom CSS
Header	Configure header height, sticky mode, topMenuMode, card slots (left / center / right), menus and custom CSS
YAML	Direct YAML editing of both configs — useful for power users or copy-paste workflows

Card editors

All card fields (bottomCard, leftCard, centerCard, rightCard and stack items) use YAML format — the same format you already use in Home Assistant. Example:

type: custom:button-card
entity: light.living_room
name: Living Room
icon: mdi:sofa

Save behaviour

Storage mode (default): changes are saved directly to Lovelace via WebSocket and the page reloads automatically.
YAML file mode (ui-lovelace.yaml): the editor generates a YAML snippet to copy-paste into your config file.

📦 Installation

HACS

This integration can be installed manually or via HACS when available.

Manual Install

Copy the JS file to:

/config/www/sidebar-card.js

Then add the resource:

url: /local/sidebar-card.js
type: module

Restart or reload resources.

🚀 Basic Setup

Add to your dashboard YAML:

sidebar:
  enabled: true
  width: { mobile: 0, tablet: 16, desktop: 18 }

header:
  enabled: true
  sticky: true
  height: 72

🧭 Sidebar Configuration

🔧 Main Options

Option	Type	Default	Description
`enabled`	bool	`true`	Enables the custom sidebar
`debug`	bool	`false`	Log debug messages to console
`title`	string	""	Optional title text
`clock`	bool	`false`	Enable analog clock
`digitalClock`	bool	`false`	Enable digital clock
`digitalClockWithSeconds`	bool	`false`	Show seconds in digital clock
`twelveHourVersion`	bool	`false`	12‑hour clock format
`period`	bool	`false`	Show AM / PM when using 12‑hour mode
`date`	bool	`true`	Show date
`dateFormat`	string	`DD MMMM`	Moment‑style format
`updateMenu`	bool	`true`	Highlight active menu item
`hideHassSidebar`	bool	`false`	Hide default HA sidebar
`hideTopMenu`	bool	`false`	Hide default HA top bar
`showTopMenuOnMobile`	bool	`true`	Show top bar only on mobile
`width`	number/object	`18`	% width or responsive config
`breakpoints.mobile`	int	`767`	Mobile max width
`breakpoints.tablet`	int	`1024`	Tablet max width
`hideOnPath`	list	—	Paths where sidebar hides
`menuStyle`	string	`list`	`list / wide / buttons / grid`
`showLabel`	bool	`true`	Show menu text labels
`template`	Jinja2	—	HTML rendered above menu
`bottomCard`	Lovelace card	—	Card shown at bottom of sidebar

📐 Responsive Width

width:
  mobile: 0
  tablet: 16
  desktop: 18

📋 Sidebar Menu Items

sidebarMenu:
  - action: navigate
    navigation_path: "/lovelace/home"
    name: "Home"
    icon: mdi:home
    background_color: "var(--blue)"
    icon_color: "#000"
    text_color: "#000"
    state: light.living_room
    conditional: "{{ is_state('alarm_control_panel.house','disarmed') }}"

Actions Supported

Action	Description
`navigate`	Go to a Lovelace view
`more-info`	Open entity dialog
`toggle`	Toggle entity
`call-service`	Call Home Assistant service
`service-js`	Execute JavaScript
`url`	Open a URL
`toggle-sidebar`	Toggle the default HA sidebar (drawer)
`toggle-topmenu`	Toggle the HA top bar (or trigger `flip` mode when enabled)

Extra Item Fields

Field	Description
`name`	Label text
`icon`	MDI icon
`background_color`	Background colour
`icon_color`	Icon colour
`text_color`	Text colour
`state`	Entity used to mark active state
`conditional`	When evaluates false → hides the item

🎨 Menu Styles

`menuStyle`	Description
`list`	Simple legacy list style
`wide`	Pill‑style items with icon + label + colored background
`buttons`	Square button style (icon with optional label)
`grid`	Compact app‑icon style grid

Example — wide style

sidebar:
  menuStyle: wide
  showLabel: true

- action: navigate
  name: "Energy"
  icon: mdi:solar-power-variant
  navigation_path: "/energy"
  background_color: "rgba(255, 200, 140, 0.95)"
  icon_color: "#0f172a"
  text_color: "#0f172a"

🧱 Header Configuration

header:
  enabled: true
  sticky: true
  height: 72                       # minimum header height (px)
  headerMenuStyle: wide            # list / wide / buttons / grid (same as sidebar)
  headerMenuShowLabel: true
  headerMenuPosition: center       # left / center / right

  # Home Assistant top bar behavior (optional)
  topMenuMode: overlay             # overlay / push / flip
  flipDuration: 5                  # seconds to keep HA top bar visible in flip mode

  # Optional icon menus (left / right)
  leftMenu:
    - icon: mdi:menu
      name: Sidebar
      action: toggle-sidebar

  rightMenu:
    - icon: mdi:application
      name: Top bar
      action: toggle-topmenu

Option	Type	Default	Description
`enabled`	bool	`true`	Enable custom header
`sticky`	bool	`true`	Make header sticky to the top
`height`	int	`72`	Minimum header height in pixels (can grow with content)
`style`	string	—	Extra CSS applied inside the header-card (supports `:host { ... }`)
`topMenuMode`	string	`overlay`	How to handle HA default top bar: `overlay`, `push`, or `flip`
`flipDuration`	number	`5`	Flip mode only: seconds to keep HA top bar visible before flipping back
`headerMenuStyle`	string	`wide`	Header menu style (`list / wide / buttons / grid`)
`headerMenuShowLabel`	bool	`true`	Show text labels in header menu
`headerMenuPosition`	string	`right`	Place header menu in `left / center / right` area
`leftMenu`	list	—	Icon buttons shown on the far left (e.g. toggle sidebar)
`rightMenu`	list	—	Icon buttons shown on the far right (e.g. toggle top bar)
`headerMenu`	list	—	Main header menu (styled buttons)
`leftCard`	Lovelace card	—	Any Lovelace card rendered in the left slot
`centerCard`	Lovelace card	—	Any Lovelace card rendered in the center slot
`rightCard`	Lovelace card	—	Any Lovelace card rendered in the right slot

🧩 Top Bar Modes (`topMenuMode`)

overlay (default): your header stays visible; HA top bar can be shown/hidden without pushing the view.
push: when HA top bar is visible, the content is pushed down using the real top bar height.
flip: your header “flips” to reveal HA top bar for a few seconds, then flips back. Use flipDuration to control how long HA top bar stays visible.

To trigger the behavior, use a menu item with:

action: toggle-topmenu

Header Menu Items

headerMenu:
  - action: navigate
    name: "Home"
    icon: mdi:home
    navigation_path: "/lovelace/home"
    background_color: "rgba(205,255,190,.95)"
    icon_color: "#0f172a"
    text_color: "#0f172a"

Header Cards

leftCard:
  type: ...
centerCard:
  type: ...
rightCard:
  type: ...

Supports any Lovelace card.

🎨 Styling & CSS Variables

Add under the style: key, e.g.:

style: |
  :host {

🔷 GRID Mode (`menuStyle: grid`)

--sidebar-grid-margin-y
--sidebar-grid-gap
--sidebar-grid-item-padding
--sidebar-grid-box-size
--sidebar-grid-radius
--sidebar-grid-bg
--sidebar-grid-icon-size
--sidebar-grid-icon-color
--sidebar-grid-label-margin-top
--sidebar-grid-font-size
--sidebar-grid-line-height
--sidebar-grid-font-weight
--sidebar-grid-text-color
--sidebar-grid-active-border
--sidebar-grid-active-bg
--sidebar-grid-active-icon-color
--sidebar-grid-active-text-color
--sidebar-grid-columns
--sidebar-grid-rows
--sidebar-grid-row-height

🟥 BUTTON Mode (`menuStyle: buttons`)

--sidebar-button-margin-y
--sidebar-button-gap
--sidebar-button-item-gap
--sidebar-button-size
--sidebar-button-box-size
--sidebar-button-radius
--sidebar-button-bg
--sidebar-button-icon-color
--sidebar-button-icon-size
--sidebar-button-font-size
--sidebar-button-line-height
--sidebar-button-text-color
--sidebar-button-font-weight
--sidebar-button-active-border-width
--sidebar-button-active-border-color
--sidebar-button-active-shadow-color
--sidebar-button-active-icon-color
--sidebar-button-active-text-color

🟩 WIDE Mode (`menuStyle: wide`)

--sidebar-wide-margin-y
--sidebar-wide-gap
--sidebar-wide-padding-x
--sidebar-wide-height
--sidebar-wide-radius
--sidebar-wide-item-gap
--sidebar-wide-bg
--sidebar-wide-icon-color
--sidebar-wide-icon-size
--sidebar-wide-font-size
--sidebar-wide-line-height
--sidebar-wide-text-color
--sidebar-wide-font-weight
--sidebar-wide-active-border-width
--sidebar-wide-active-border-color
--sidebar-wide-active-bg
--sidebar-wide-active-opacity
--sidebar-wide-active-icon-color
--sidebar-wide-active-icon-size
--sidebar-wide-active-text-color

🧠 Common Sidebar Variables

--sidebar-selected-bg
--sidebar-icon-color
--primary-text-color

🖼 Header Variables

--header-background
--header-backdrop-filter
--header-radius
--header-height

🛠 Troubleshooting

Disable conflicting layout plugins when testing
Clear browser cache and reload resources
Test without theme customisation first

❤️ Credits

Thanks DBuit for original work

Built for the HA community 🙂

🔄 Header Top Menu Modes (NEW)

The custom header can manage the Home Assistant top bar in three different ways.

Mode	Description
`overlay`	HA top bar overlays the content
`push`	Content is pushed down by the HA top bar
`flip`	Animated cylindrical flip between custom header and HA top bar

🌀 Flip Mode

The flip mode creates a smooth cylindrical rotation effect between:

Your custom header
The original Home Assistant top bar

✔ No layout jumps
✔ No content shifting
✔ Identical occupied space

Configuration

header:
  enabled: true
  sticky: true
  topMenuMode: flip
  flipDuration: 5   # seconds (optional, default: 5)

Trigger example

headerMenu:
  - action: service-js
    name: "Top Menu"
    icon: mdi:swap-vertical
    service: |
      if (window.silvioFlipTopMenu) {
        window.silvioFlipTopMenu();
      }

or

rightMenu:
  - icon: mdi:application
    name: Top bar
    action: toggle-topmenu

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
dist		dist
example		example
img		img
src		src
LICENSE		LICENSE
README.it.md		README.it.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
hacs.json		hacs.json
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Supportami / Support Me

🧭 Custom Sidebar & Header for Home Assistant

Header Flip Mode

Header Push Mode

📸 Screenshots

⭐ Main Features

🖊️ Graphical Editor (Admin only)

How to open it

Editor tabs

Card editors

Save behaviour

📦 Installation

HACS

Manual Install

🚀 Basic Setup

🧭 Sidebar Configuration

🔧 Main Options

📐 Responsive Width

📋 Sidebar Menu Items

Actions Supported

Extra Item Fields

🎨 Menu Styles

Example — wide style

🧱 Header Configuration

🧩 Top Bar Modes (topMenuMode)

Header Menu Items

Header Cards

🎨 Styling & CSS Variables

🔷 GRID Mode (menuStyle: grid)

🟥 BUTTON Mode (menuStyle: buttons)

🟩 WIDE Mode (menuStyle: wide)

🧠 Common Sidebar Variables

🖼 Header Variables

🛠 Troubleshooting

❤️ Credits

🔄 Header Top Menu Modes (NEW)

🌀 Flip Mode

Configuration

Trigger example

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🧩 Top Bar Modes (`topMenuMode`)

🔷 GRID Mode (`menuStyle: grid`)

🟥 BUTTON Mode (`menuStyle: buttons`)

🟩 WIDE Mode (`menuStyle: wide`)

Packages