Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
The Lovelace interface can be extended with custom cards, entities, rows and various plugins.
Installing a plugin
For most plugins, the process is as follows.
1: Read the docs
Be sure to read the documentation of the plugin you are interested in. The process of installing it might be totally different from what I'm describing below.
2: Download the plugin.
Most plugins are distributed as a single
.js file, e.g.
Make sure you get the Raw version if downloading from Github.
Place the file somewhere in
<home assistant config>/www/ e.g.
www/ doesn't exist, you should create it and then restart Home Assistant.
Note: If you're comfortable with git, the easiest way to do this is to just navigate to
www/and rungit clone https://github.com/thomasloven/lovelace-card-modder
3: Import the plugin in your lovelace config
If you are using Lovelace YAML Mode add a
resources: section to your
tile: My awesome Lovelace config resources: - url: /local/plugins/card-modder.js?v=1 type: js views: ...
url is the path to your downloaded file. Replace
<config directory>/www/ with
?v=1 will help you if you ever update the plugin. See Updating a plugin
type is usually either
module. Check the documentation for the plugin to be sure.
If you are using the GUI editor for Lovelace, you can add the resources section using the Raw config editor, which you reach by entering Edit mode and then clicking the three dots in the top right corner.
4: Use the plugin
Here I can't help you. Read the documentation to find out how the plugin is used.
Updating a plugin
Sometimes things change. Plugins evolve, bugs are squashed, features are added.
To upgrade a plugin to the latest version, there are two steps to follow.
1: Get the latest version of the file(s)
2: Update the version number in the resources section.
The internet as we know it works as well as it does due to caching. When you visit a new website, your browser downloads and stores a copy of it locally, so that the next time you wish to visit it you won't have to download it again, saving time and bandwidth. Even if you didn't have a local copy saved, it's likely you still didn't get the page directly from its server. Every computer your request has to go through on the way to the target may cache the page and serve the saved version instead.
This is a great thing, but can cause problems. For example, when you reload your lovelace interface after upgrading to the latest version of
card-tools.js, your browser may think "Hey, I know this file already. No need to bother the server." and helpfully hand you the old version. Bummer.
However. If you use the version number described above, the browser might think "Hm... card-tools.js?v=2, eh? Well, I have a card-tools.js?v=1, but that's obviously a totally different file. Hey! Server! I want card-tools.js?v=2".
Meanwhile, the server will (in this case) ignore anything from the
? and on, and just serve the latest version of
card-tools.js. Problem solved.
Seriously, this is important. Every time you change anything with the .js files you MUST update the version number.
Note: The version number doesn't have to be a number. As long as theres something after the
?and this something is unique and has never been used before by you for that file, the trick will work.
Note: The same trick works for images like
If something is not working, the first thing you should do is to check for error messages on screen or in the home assistant and browser logs.
Example of a clear error message telling you exactly what to do. Read them.
Home Assistant log
You can find the Home Assistant log by going to `/dev-info and clicking the refresh symbol in the lower right corner. Look for anything that seems even remotely relevant. Most recent things are at the bottom.
In Google Chrome you can reach the browser log via ctrl+shift+j, cmd+alt+j or by right-clicking the page, selecting "Inspect" and then "Console at the top of the panel that pops up.
In the example above, the log says that the file
not-card-modder.js can't be found. Perhaps I specified the wrong url in my
Some common error messages:
Uncaught SyntaxError: Unexpected token <
You didn't download the Raw version from github. See Install step 2 above.
Uncaught SyntaxError: Unexpected identifier
You may have specified the resource as
type: js when it's supposed to be
type: module. Read the docs again to make sure.
Cannot call a class constructor without |new| /
Class constructor [...] cannot be invoked without 'new'
Make sure to configure your
Plugins don't work on iOS devices
Make sure to configure your
Things suddenly stopped working
First make sure you have the latest version of the plugin. Even if you didn't change anything. This includes reading the docs again. Then ask for help.
Note: If the plugin requires other plugins, such as card-tools (read the docs again to see if they do), make sure those are updated too.