HA Flow Builder Card is a Home Assistant custom dashboard card for creating compact, live flow diagrams without editing YAML. Pick one main entity, then add entity trees above, right, below, or left of it. Every node can contain sub-entities and the card calculates all positions and connections automatically.

It is intentionally domain-neutral: the same card can show energy, heating, water, ventilation, data, or any other entity-based flow.

• Fully graphical Lovelace card editor
• One central main entity with recursive parent/child branches
• Entity nodes and calculated Sum nodes
• Per-node Card or Circle shape, with an optional borderless appearance
• Optional large Battery or Buffer tank container rendering
• Temperature-aware tank gradients built from ordered Extra value sensors
• Up to four sibling nodes per level and four hierarchy levels
• Native Home Assistant entity pickers
• Live names, icons, states, and units from hass.states
• Up to four extra values per node, each with an optional icon
• Compact Battery, Heat pump, Water heater, Radiator, Solar, Grid, Home load, EV charger, Water, and Gas containers
• Optional fixed value and unit while an entity is active, useful for switches and consumers
• Optional directional In and Out entities sharing one bidirectional flow line
• Optional entity value on every connection
• Static lines, conditionally moving flow balls, and directional arrows
• A distinct theme-aware color for every connection
• Connections terminate at measured Card/Circle edges
• Compact value tiles with entity names positioned outside the tile
• Balanced spacing that centers the complete drawing and uses available space
• Explicit or sign-based automatic flow direction
• Automatic, responsive four-direction layout
• Native Home Assistant Sections resizing with adaptive card height
• Graceful missing, unknown, and unavailable states
• Dark and light theme support through Home Assistant theme variables
• Keyboard-accessible add, remove, and reorder controls

Screenshots will be added after the first Home Assistant integration test.

1. Run npm install and npm run build, or use the already generated bundle in dist.
2. Copy dist/ha-flow-builder-card.js to the www directory in your Home Assistant configuration directory.
3. In Home Assistant, open Settings → Dashboards, open the three-dot menu, and choose Resources.
4. Add /local/ha-flow-builder-card.js as a JavaScript module.
5. Refresh the browser. A hard refresh may be needed after replacing an older bundle.
6. Edit a dashboard, choose Add card, search for HA Flow Builder Card, and configure it entirely in the graphical editor.

No YAML configuration is required for normal use.

The card is registered as EasyFlowCard with type custom:easyflow-card. Existing dashboards using the former custom:ha-flow-builder-card type remain supported as a compatibility alias.

1. Every node offers the same Entity or Math tabs. Under Math, choose Sum or Average.
2. Under Top, Right, Bottom, or Left, click Add node and choose its type.
3. Pick an entity. The live preview updates and Home Assistant stores the configuration immediately.
4. Add up to four root nodes per direction and up to twelve children beneath a node. Under any node, choose Add child node to create structures such as a solar total, its inverters, and each inverter's PV flanks. Use the arrow buttons to reorder siblings. To configure a group of matching devices, add one child manually and select its primary entity, Extra values, icons, appearance, and connection settings. Add similar devices then finds other devices from the same integration/configuration and device family, copies those settings, and maps every selected entity to its equivalent on each device. A Tado template therefore only produces matching Tado devices—not unrelated temperature sensors. Existing devices are not duplicated and no Home Assistant API call is made.
5. Math nodes have no Home Assistant entity of their own. For Main, Sum or Average uses the configured Math inputs. Those inputs stay visible, making Average suitable for the top and bottom sensors of a buffer tank. For directional nodes, Math uses their direct child nodes. Compatible child Extra values are also grouped and calculated. Nested Math nodes are supported.
6. Compatible power (W, kW, MW, GW) and energy (Wh, kWh, MWh, GWh) values are converted before they are added. Other values are combined when their units match. Missing, unavailable, non-numeric, or incompatible values are ignored.
7. Enter an optional Custom name above the Entity/Math selector. Use the right-aligned Extra values tab to add up to four secondary values, each with an entity, a value source (the entity state or one of its attributes), and an optional icon. For example, select a climate entity and its current_temperature attribute to display the measured temperature. For Main Math this tab is called Math inputs. Existing configurations with the former single secondary entity are migrated automatically to the first Extra value. Expand More options to select the display mode. Standard offers the existing Card or Circle shape and optional Borderless appearance. Container offers purpose-built compact Battery, Heat pump, Water heater, Radiator, Solar panel, Electricity grid, Home load, EV charger, Water meter, and Gas meter designs. Water heater has a large heating-coil visual; Radiator uses a familiar panel-radiator design. Both glow warm red while their primary entity is active and become neutral when idle. Utility containers animate while their primary numeric entity is non-zero and become neutral when idle. Use Extra values for related readings such as daily energy, state of charge, voltage, flow, cost, or temperature. Large container offers the original large Battery or Buffer tank. For a switch or another consumer, enter a Fixed value while active and its unit. The fixed value replaces the entity state while it is active; while inactive the node displays 0 and contributes 0 to parent Sum nodes.
8. Optionally select an In entity and/or Out entity under In & out values. In flows from the parent into the node; Out flows from the node to its parent. Both values share one bidirectional line and their position-aware arrows appear inside the node. If both channels are active simultaneously, the greatest absolute power controls the movement and line color.
9. Expand Connection to … inside a node block to place an optional sensor value on its parent connection and select the visual style or dot direction. Its style is also used for directional override lines.

For a Battery container, the primary numeric value controls the fill level from 0 to 100 and the fill changes from red through yellow to green. Extra values and In/Out values are displayed inside the battery. Large containers use roughly five times the surface area of the original compact container and scale down on narrow cards.

For a Buffer tank, set the Maximum temperature under Appearance. The scale moves from deep blue through violet to red, ending in glowing red at the configured maximum. Numeric temperature Extra values are placed in list order from the top to the bottom of the tank and create a multi-stop vertical gradient. When no Extra value contains a temperature, the primary temperature is used as a single-color fill.

For automatic connection direction, a positive numeric state flows from source to target, a negative state flows from target to source, and zero or a non-numeric/missing state shows no direction.

Without directional overrides, flow balls move inward from branch nodes toward the main/home entity and use the branch node's primary value as their condition. For Sum nodes, that condition uses the calculated primary total. With In/Out overrides, every line uses its own selected entity: In moves from parent to node and Out moves from node to parent.

Absolute power strictly above 10 W shows continuous flow. A power value below -10 W reverses the normal movement direction. Values in kW and MW are converted to watts before applying the threshold. A changing degree value (°C/°F) shows flow for 15 seconds after the change. kWh, unrelated units, missing entities, unknown, and unavailable do not show balls. Every connection remains visible even while inactive.

For Fixed value while active, the configured unit is display-only. Animation uses the absolute fixed number with the same strict > 10 threshold regardless of whether the displayed unit is W, °C, or another unit.

Requirements:

• Node.js 20.19 or newer
• npm 10 or newer

Install the dependencies once, then start the fixed local server:

npm install
npm run dev

The development resource is always available at:

http://localhost:32123/ha-flow-builder-card.js

The server uses HTTP on port 32123, enables CORS, and requires no local certificate setup. It serves a development-only entry containing Vite's reload client. After a successful source update, the Home Assistant browser tab performs a full page reload; custom elements are not hot-replaced. The production build uses a different entry and never includes this reload code.

With npm run dev running:

1. Open Settings.
2. Open Dashboards.
3. Open the three-dot menu and choose Resources.
4. Choose Add resource.
5. Enter http://localhost:32123/ha-flow-builder-card.js.
6. Select JavaScript Module and add the resource.
7. Keep the development server running while editing the card source.

This repository does not connect to or configure Home Assistant. If Home Assistant is opened through HTTPS, the browser may block this HTTP development resource as mixed content; no certificate or HTTPS configuration is created by this project.

Install and validate:

npm install
npm run typecheck
npm run lint
npm test
npm run build

Useful scripts:

• npm run build creates dist/ha-flow-builder-card.js.
• npm run dev serves the development-only module with automatic page reload.
• npm run typecheck checks strict TypeScript types.
• npm run lint runs ESLint.
• npm test runs the Vitest unit suite.
• npm run format formats the repository with Prettier.
• npm run format:check verifies formatting without changing files.

The persisted configuration is versioned, serializable plain data. Runtime responsibilities are separated:

• domain defines Entity/Math nodes, node shapes, directional flow overrides, recursive branches, connections, directions, and the V11 config schema.
• ConfigNormalizer validates incomplete/older input, applies defaults, enforces tree limits, and migrates earlier configurations to V11.
• EntityPresenter turns Home Assistant state objects and calculated Sum/Average values into safe display models.
• LayoutEngine is the sole owner of node coordinates and connection geometry.
• FlowDirectionResolver converts explicit modes or signed entity values into visual directions.
• components render nodes, connections, and the composed diagram.
• editor contains cohesive editors for nodes, branches, and connections.
• card coordinates Home Assistant lifecycle methods and diagram rendering.

This structure leaves room for calculated nodes, richer styling, templates, and alternative layout strategies without coupling those features to the Lovelace card component.

Home Assistant stores a versioned plain-data representation generated by the visual editor. It contains main and four recursive branch trees. Every tree node stores its node type and settings, parent connection, and child nodes as separate serializable objects. This is an internal format for persistence and debugging; ordinary users should use the graphical editor and should not write it manually.

The repository includes hacs.json and produces the expected single-file frontend bundle. A future release will add the repository to HACS and replace this section with the standard one-click installation instructions.

The card targets modern browsers supported by current Home Assistant frontends.

The card implements both masonry sizing and the Home Assistant Sections getGridOptions() API. It defaults to full width, supports resizing from 6 to 12 columns and 8 to 16 rows, and expands the diagram to use the assigned height. Its preferred height grows with every vertical tree level so labels, circles, and directional values retain useful spacing.

The graphical editor preserves Home Assistant-managed grid_options and other external top-level card metadata on every save, so manually selected width and height values are not reset while editing nodes.