Home Assistant Components Loader

@kipk/load-ha-components loads and verifies Home Assistant UI custom elements used by a custom card or panel. It is intended for code running under the Home Assistant DOM tree.

Version 2.x is published as an ES module and exposes a single strict loading API.

Installation

npm install @kipk/load-ha-components@^2.0.0

Usage

import {
  HaComponentsLoadError,
  loadHaComponents,
} from '@kipk/load-ha-components';

try {
  const result = await loadHaComponents(['ha-form', 'ha-icon-button']);
  console.log(result.loaded);
} catch (error) {
  if (error instanceof HaComponentsLoadError) {
    // Pick an application-specific fallback here.
    console.warn('Unavailable Home Assistant components:', error.result.missing);
  } else {
    throw error;
  }
}

loadHaComponents() is the only loading API. It resolves only after every requested custom element is defined, and rejects with HaComponentsLoadError if a strategy fails, times out, the DOM is unavailable, or an element remains absent. The package does not log errors or choose a fallback itself.

The result has requested, alreadyDefined, loaded, missing, and attemptedStrategies arrays. Requests are trimmed, de-duplicated, and retain their first-seen order. timeoutMs is the sole option and defaults to 10 seconds when omitted or invalid.

Loading strategies

Most components use Home Assistant's Configuration/Automations loading path. ha-target-picker and ha-date-range-picker use the History panel bundle instead:

await loadHaComponents(['ha-target-picker']);

The loader feature-detects Home Assistant's panel resolver helpers, shares concurrent strategy loads, and retries a strategy after a failure or an import that did not define the requested element. It does not guarantee that an arbitrary unknown internal component can be loaded: unknown names use the historical Configuration/Automations strategy and still fail strictly if absent.

ha-target-picker relies on Home Assistant context. Render it below the <home-assistant> tree so its Lit Context providers, including labels, are available; loading its module alone does not make it work outside that tree.

Migrating from 1.x to 2.x

Version 2.0.0 deliberately changes the contract. Previously, loading failures were caught and hidden. In 2.x, callers must handle the rejected promise at the UI boundary where an appropriate fallback can be selected.

Existing consumers that declare ^1.0.3 do not select this major version and remain on the compatible 1.x line until they migrate explicitly.

try {
  await loadHaComponents(['ha-target-picker']);
  // Render the picker only after successful verification.
} catch (error) {
  if (error instanceof HaComponentsLoadError) {
    // Keep the editor in a safe state or render a local fallback.
  } else {
    throw error;
  }
}

Default components

The following components are included in the default list:

• ha-form
• ha-icon
• ha-icon-button
• ha-selector
• ha-textfield
• ha-icon-picker
• ha-entity-picker
• ha-select
• ha-dialog
• ha-sortable
• ha-svg-icon
• ha-alert
• ha-button
• ha-color-picker
• ha-badge
• ha-sankey-chart

License

MIT