On this page

Not every change needs a running Home Assistant. The frontend repository has two apps that run the real frontend code against fake data: the gallery and the demo.

The gallery shows components, dashboard cards, and more-info views on their own, in every state that matters: on, off, unavailable, loading, in light and dark, and right to left. It is a development tool: run it locally to build and check a component without a Home Assistant.

Run it locally on port 8100:

Shell
pnpm dev:gallery

The gallery lives in the gallery/ folder:

  • gallery/src/pages/<category>/<page>.markdown: the description of a page, with optional front matter for title and subtitle.
  • gallery/src/pages/<category>/<page>.ts: the live demo of the same page. It defines a custom element named after the page, like demo-components-ha-button for components/ha-button.
  • gallery/sidebar.js: the sections of the sidebar and the order of pages in them.
  • gallery/src/data/ and gallery/src/components/: fake hass objects, sample states, and helpers like demo-cards and demo-more-infos that render a list of card configurations or entities.

Gallery pages use the real components from src/, not copies. When your change alters how a documented component behaves, update its gallery page in the same pull request. Maintainers can add the needs design preview label to deploy a preview of the gallery for your pull request.

Note

The published design guidance lives in the Design area of this site, not in the gallery. It replaces design.home-assistant.io. The components, dashboard cards, and more-info views each have a page there, with usage, specs, accessibility, and live examples. When your change alters how a component looks or behaves, update its page there too, with a pull request to this site.

The demo

The demo is the complete Home Assistant frontend, running against a mocked backend in your browser. It is published at demo.home-assistant.io. It is the easiest way to load the full app without a server, for example to check a dashboard or take screenshots.

Run it locally on port 8090:

Shell
pnpm dev:demo

The demo has several homes to choose from. Select one with the demo query parameter, and a page with the part after the #:

http://localhost:8090/?demo=<slug>#/energy

The slugs are in demo/src/configs/demo-configs.ts. Each home has its own folder in demo/src/configs/, with its entities, dashboard, and theme. The mocked WebSocket and REST APIs live in demo/src/stubs/.

The gallery imports some of those stubs too. When you change a stub, check both the demo and the gallery pages that use it.

Some demo data is generated from Core: the action descriptions in src/fake_data/demo_services.ts, and the trigger and condition descriptions in demo/src/stubs/. Don't edit those by hand. Run script/gen_demo_core_data to regenerate them from the dev branch of Core.

Embed cards on other sites

The demo also builds embed.js, which puts dashboard cards on any web page with the <ha-embed-provider> and <ha-embed-card> elements. Card authors use it for live demos of their cards. Its code is in demo/src/embed/, and demo/src/html/components.html.template is the page that documents it, at /components.html of the demo.

The provider registers its own set of mocks. Most come from the stubs in demo/src/stubs/, and a few, like energy, are defined in ha-embed-provider.ts. A fix to a stub reaches each of the demo, the embed, and the gallery pages that import that stub, and they don't all import the same ones. The calendar stub, for example, is used by the embed and the gallery, but not by the demo. For a new stub, import it in ha-embed-provider.ts and call it in the constructor too.

The production build of the script loads its other files from the site it came from, so it works on other sites too. The development and legacy builds load them from the site of the page instead, so try changes that need to work on other sites with a production build.

Both start in English. Add --fetch-translations to load the latest translations, like pnpm dev:demo --fetch-translations. Both also accept the background flags.

Was this page helpful?

Last updated on .