- Installing a plugin
- 1: Read the docs
- 2: Download the plugin.
- 3: Import the plugin in your lovelace config
- In Home Asistant 0.107 or later
- 4: Use the plugin
- Updating a plugin
- 0: Read the documentation to see what's changed
- 1: Get the latest version of the file(s)
- 2: Home Assistant version 0.106 or earlier: Update the version number in the resources section.
- Seriously, this is important. Every time you change anything with the .js files you MUST update the version number.
- Common problems
- On screen
- Home Assistant log
- Browser console
- Some common error messages:
- Cannot convert undefined or null to object at Function.getPrototypeOf
- Uncaught SyntaxError: Unexpected token <
- Uncaught SyntaxError: Unexpected identifier
- Can't find card-tools but card-tools is installed (you can see the green text in the browser console)
- Cannot call a class constructor without |new| / Class constructor [...] cannot be invoked without 'new'
- Plugins don't work on iOS devices
- Things suddenly stopped working
- Clearing cache
LoadingMod plugin templates
LoadingMy Lovelace Plugins
Loadingold Dev Setup
LoadingPreLoading Lovelace Elements
Clone this wiki locally
The Lovelace interface can be extended with custom cards, entities, rows and various plugins.
I recommend using HACS to install and keep track of plugins. If you do, steps two and three in the installation instructions below, and the updating procedure will be different. See the docs for HACS. Steps one(!) and four, as well as the rest of this article still applies, though.
For most plugins, the manual process is as follows.
Through this guide
card-mod is used as an example only. The same process applies to any plugin, but references to e.g.
card-mod.js will have to be replaced accordingly (I can't believe I have to make this comment!).
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.
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-mod
There are two ways to import a plugin. The easiest is via the graphical user interface (GUI).
Go to your profile
At the bottom of the sidebar, there's a button with your initials in it. Click that.
Enable "Advanced Mode"
Make sure the toggle is checked
Go to "Configuration" The gear symbol near the bottom of the sidebar
Select "Lovelace Dashboard"
Select the "Resources" tab
If you don't see the tab, go back and make sure you enabled "Advanced Mode". It can be both at the top and at the bottom of the page, depending on your screen size.
Click the Plus to add a new resource. The
urlis the path to your downloaded file. Replace
Finish by clicking "Create"
Refresh your browser
The second way is to add the resources to the
lovelace section of your
See Dashboards and Views.
Here I can't help you. Read the documentation to find out how the plugin is used.
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.
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-mod.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-mod.js?v=2, eh? Well, I have a card-mod.js?v=1, but that's obviously a totally different file. Hey! Server! I want card-mod.js?v=2".
Meanwhile, the server will (in this case) ignore anything from the
? and on, and just serve the latest version of
card-mod.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.
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 console via F12, 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. All browsers have something similar. For mobile browsers, you may have to connect your phone to a computer and debug from there.
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
This is due to a change in Home Assistant 0.88 and requires an update to the card. If the card you are trying to use depends on card-tools, updating card-tools will fix it. As of April 2020, if you get this error it's time to give up that specific custom card and move on.
You didn't download the Raw version from github. See Install step 2 above. And if you did, see Upgrade step 2 above.
You may have specified the resource as
type: js when it's supposed to be
type: module. Read the docs again to make sure.
Can't find card-tools but card-tools is installed (you can see the green text in the browser console)
You may have specified card-tools as
type: module. It should be
Cannot call a class constructor without |new| /
Class constructor [...] cannot be invoked without 'new'
Make sure to configure your
Make sure to configure your
- First make sure you have the latest version of the plugin and any dependencies (such as card-tools). Even if you didn't change anything. This includes reading the docs again - things change.
- Update the version numbers as described in Updating a Plugin
- Clear your cache (See below)
- Try again
- If it doesn't work, go through the Common Problems section again.
- Then ask for help.
If you need to go that far, including as many as possible of the following points in your question will get you better help faster:
- Relevant information about your setup
- What you were trying to do
- How you were trying to do it
- What you expected to happen (bonus points if you add why you expected that to happen)
- What happened instead
- What other things you have tried in order to fix it
- Relevant screenshots
In Google Chrome, the best way to clear your cache is:
- Press F12 to open the developers console
- Right click the refresh button to the left of the address bar
- Select the bottom option to reset the cache and perform a hard refresh.
In Safari, the easiest way is to press Option+Command+E to clear cache, followed by Command+R to refresh the page.