Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add create helper functions for custom cards #4853

merged 2 commits into from Feb 14, 2020


Copy link

iantrich commented Feb 12, 2020

Breaking change

Proposed change

Exposing the create helpers functions so that custom cards can use them. Will add this to the dev docs as they are added.

Type of change

  • Dependency upgrade
  • Bugfix (non-breaking change which fixes an issue)
  • New feature (thank you!)
  • Breaking change (fix/feature causing existing functionality to break)
  • Code quality improvements to existing code or addition of tests

Example configuration

Simple custom card implementation to use it

/* eslint-disable @typescript-eslint/no-explicit-any */
import { LitElement, html, customElement, property, CSSResult, TemplateResult, css, PropertyValues } from 'lit-element';
import { HomeAssistant, hasConfigOrEntityChanged } from 'custom-card-helpers';
import deepClone from 'deep-clone-simple';

import { CustomCardConfig } from './types';
import { CARD_VERSION } from './const';

import { localize } from './localize/localize';

/* eslint no-console: 0 */
  `%c  custom-card \n%c  ${localize('common.version')} ${CARD_VERSION}    `,
  'color: orange; font-weight: bold; background: black',
  'color: white; font-weight: bold; background: dimgray',

export class CustomCard extends LitElement {
  @property() public hass?: HomeAssistant;
  @property() private _config?: CustomCardConfig;
  @property() private _helpers?: any;

  public setConfig(config: CustomCardConfig): void {
    if (!config) {
      throw new Error(localize('common.invalid_configuration'));

    this._config = {


  protected shouldUpdate(changedProps: PropertyValues): boolean {
    return hasConfigOrEntityChanged(this, changedProps, false);

  protected render(): TemplateResult | void {
    if (!this._config || !this.hass || !this._helpers) {
      return html``;

    const config = deepClone(this._config);
    delete config['type'];
    const element = this._helpers.createRowElement(config);

    if (this.hass) {
      element.hass = this.hass;

    return html`

  private async loadCardHelpers(): Promise<void> {
    this._helpers = await (window as any).loadCardHelpers();

  static get styles(): CSSResult {
    return css``;

Additional information

  • This PR fixes or closes issue: fixes #
  • This PR is related to issue:
  • Link to documentation pull request:


  • The code change is tested and works locally.
  • There is no commented out code in this PR.
  • Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

Copy link

balloob left a comment

This looks good.

In a future PR, we should break up importing the components from the createXElement functions. That way we can tweak performance and loading a bit more . -> #4857

Copy link

thomasloven left a comment

I like how this is not polluting window like anything I would have come up with.

Agree with Bram about deferred exports. That's a neat feature.

@thomasloven thomasloven mentioned this pull request Feb 13, 2020
0 of 9 tasks complete

This comment has been minimized.

Copy link
Member Author

iantrich commented Feb 14, 2020

thoughts on exposing action handler? That's another thing that keeps changing


This comment has been minimized.

Copy link

balloob commented Feb 14, 2020

Makes sense I think. But let's discuss it in a new PR and get this merged so we can do a dev UI release so people can start testing their custom cards against it .

@balloob balloob merged commit f5384e8 into home-assistant:dev Feb 14, 2020
2 checks passed
2 checks passed
cla-bot Everyone involved has signed the CLA
continuous-integration/travis-ci/pr The Travis CI build passed
@lock lock bot locked and limited conversation to collaborators Feb 15, 2020

This comment has been minimized.

Copy link

bramkragten commented Feb 24, 2020

Does this PR already have documentation?


This comment has been minimized.

Copy link
Member Author

iantrich commented Feb 24, 2020


@iantrich iantrich deleted the iantrich:custom-card-helpers branch Apr 1, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants
You can’t perform that action at this time.