[JS+Editor Module] EV Car Card

[jgvsaramago]

Module post template

EV Car Card

Version: v1.0.0
Creator: João Saramago

Important

Supported cards:

• Button

EV status card showing a car image, battery bar, and range. Use the card's sub buttons to show status — the overlay automatically stays clear of the sub-button row when present. Sub-button colors can be customized per entity state in the editor.

Two layouts are available: Default sizes the card to fit your dashboard row — set a minimum height so the image has room to display. Square forces the card into a 1:1 square that fills the available space.

You can upload your car image via Home Assistant's Media browser and copy its URL into the image_url field, and optionally set a max width to control its size.

Configure this module via the editor or in YAML, for example:

ev_car_card:
    image_url: /local/car_images/megane_etech.png
    battery_entity: sensor.car_battery_level
    range_entity: sensor.car_range
    card_layout: square

A more complete example using the other available options:

ev_car_card:
    image_url: /local/car_images/megane_etech.png
    image_max_width: 80%
    battery_entity: sensor.car_battery_level
    range_entity: sensor.car_range
    card_layout: default
    card_min_height: 220px
    sub_button_colors:
      - index: 0
        bold: true
        states:
          - state: charging
            background: green
            text_color: white
          - state: "on"
            background: blue
            text_color: white

---

🧩 Get this Module

To use this module, simply copy and paste the following configuration into your /www/bubble/bubble-modules.yaml file.

ev_car_card:
    name: "EV Car Card"
    version: "v1.0.0"
    creator: "JoaoSaramago"
    # Post your module first, then edit it with the correct discussion URL.
    link: "https://github.com/Clooos/Bubble-Card/discussions/****"

    supported:
      - button

    description: |
        EV status card: car image, battery bar, and range.
        Use the card's sub buttons to show status — the overlay automatically
        stays clear of the sub-button row when present. Sub-button colors can be
        customized per entity state in the editor.
        <br><br>
        Two layouts are available: Default sizes the card to fit your dashboard
        row — set a minimum height so the image has room to display. Square
        forces the card into a 1:1 square that fills the available space.
        <br><br>
        Create a new Button card and set the entities below. You can upload your
        car image via Home Assistant's Media browser and copy its URL into the
        image field, and optionally set a max width to control its size.
        <br><br>
        <code-block><pre>
        ev_car_card:
            image_url: /local/car_images/megane_etech.png
            battery_entity: sensor.car_battery_level
            range_entity: sensor.car_range
            card_layout: square
        </pre></code-block>
        <br><br>
        A more complete example using the other available options:
        <br><br>
        <code-block><pre>
        ev_car_card:
            image_url: /local/car_images/megane_etech.png
            image_max_width: 80%
            battery_entity: sensor.car_battery_level
            range_entity: sensor.car_range
            card_layout: default
            card_min_height: 220px
            sub_button_colors:
              - index: 0
                bold: true
                states:
                  - state: charging
                    background: green
                    text_color: white
                  - state: "on"
                    background: blue
                    text_color: white
        </pre></code-block>

    code: |
        .bubble-container::before {
          display: none;
        }

        .bubble-container.bc-ev-card {
          overflow: hidden;
          isolation: isolate;
          contain: layout style paint;
          container-type: inline-size;
          container-name: bc-ev;
        }

        .bubble-container.bc-ev-card.bc-square-card {
          aspect-ratio: 1 / 1 !important;
          height: 100% !important;
        }

        .bubble-container.bc-ev-card:not(.bc-square-card) {
          min-height: var(--bc-ev-min-height, 200px);
        }

        .bc-ev-card .bubble-sub-button-container {
          align-self: flex-start !important;
        }

        .bubble-wrapper.bc-ev-fixed-top {
          align-items: flex-start !important;
        }

        .bubble-wrapper.bc-ev-fixed-top .bubble-content-container {
          display: flex;
          align-items: center;
          align-self: flex-start;
          overflow: hidden;
          flex-grow: 1;
          margin: 15px 0 0 0;
          min-height: unset;
        }

        .bc-ev {
          position: absolute;
          left: 0;
          right: 0;
          bottom: 0;
          top: 0;
          display: flex;
          flex-direction: column;
          box-sizing: border-box;
          padding: 0 18px 18px;
          pointer-events: none;
          contain: layout style;
        }

        .bubble-wrapper:has(.bubble-sub-button-bottom-container) .bc-ev {
          padding: 0 15px 10px;
        }

        .bc-ev-image {
          flex: 1 1 0;
          min-height: 20px;
          display: flex;
          align-items: center;
          justify-content: center;
          margin: 0 auto;
          padding: 12px;
        }

        .bc-ev-image img {
          max-width: var(--bc-ev-image-max-width, 100%);
          max-height: 100%;
          object-fit: contain;
        }

        .bc-ev-battery-row {
          display: flex;
          justify-content: space-between;
          align-items: baseline;
          margin-top: 2cqw;
          color: var(--primary-text-color);
        }

        .bc-ev-percent {
          font-size: 20px;
          font-weight: 600;
          line-height: 1;
        }

        .bc-ev-range {
          font-size: 12px;
          color: var(--secondary-text-color);
        }

        .bc-ev-bar-track {
          width: 100%;
          height: 2.2cqw;
          border-radius: 1.2cqw;
          background-color: var(--bubble-main-background-color, var(--card-background-color));
          overflow: hidden;
          margin-top: 1.6cqw;
          flex-shrink: 0;
        }

        .bc-ev-bar-fill {
          height: 100%;
          border-radius: 1.2cqw;
          background: var(--bubble-accent-color, var(--success-color, #4caf50));
        }

        @container bc-ev (max-width: 190px) {
          .bc-ev-image {
            padding: 10px;
          }
          .bc-ev-percent {
            font-size: 18px;
          }
        }

        @container bc-ev (max-width: 170px) {
          .bc-ev-percent {
            font-size: 16px;
          }
        }

        ${(() => {
          const cfg = this.config.ev_car_card || {};
          const cardLayout = cfg.card_layout || 'default';
          const moduleMem = window.__bcEV = window.__bcEV || {};
          const stateMem = moduleMem.state || (moduleMem.state = {});
          const hostStateMap = moduleMem.hostStateMap || (moduleMem.hostStateMap = new WeakMap());

          const getHostState = target => {
            if (!target) return null;
            let record = hostStateMap.get(target);
            if (!record) {
              record = {};
              hostStateMap.set(target, record);
            }
            return record;
          };

          const pruneMemStore = (store, cap = 12) => {
            const entries = Object.entries(store);
            if (entries.length <= cap) return;
            entries
              .sort((a, b) => ((a[1]?.ts ?? 0) - (b[1]?.ts ?? 0)))
              .slice(0, entries.length - cap)
              .forEach(([key]) => { delete store[key]; });
          };

          const ha = (typeof hass !== 'undefined' && hass) ? hass : this?.hass;
          if (!ha) return;

          const elements = this?.elements;
          const mainEntityId = typeof entity === 'string' ? entity : (this?.entity?.entity_id || '');
          if (!mainEntityId) return;

          const batteryId = cfg.battery_entity;
          const rangeId = cfg.range_entity;
          const imageUrl = cfg.image_url || '';
          const imageMaxWidth = cfg.image_max_width || '';

          const host = elements?.cardWrapper || card;
          const hostState = getHostState(host);
          const container =
            elements?.cardContainer ||
            host?.closest?.('.bubble-container') ||
            host;

          container?.classList.add('bc-ev-card');
          if (cardLayout === 'square') {
            container?.classList.add('bc-square-card');
            container?.style.removeProperty('--bc-ev-min-height');
          } else {
            container?.classList.remove('bc-square-card');
            container?.style.setProperty('--bc-ev-min-height', cfg.card_min_height || '200px');
          }

          try {
            const pos = getComputedStyle(host).position;
            if (!pos || pos === 'static') host.style.position = 'relative';
          } catch {}
          host?.classList?.add('bc-ev-fixed-top');

          const cleanupHostResources = () => {
            if (!hostState) return;
            if (hostState.resizeObserver) {
              try { hostState.resizeObserver.disconnect(); } catch {}
              hostState.resizeObserver = null;
            }
            if (hostState.parentObserver) {
              hostState.parentObserver.disconnect();
              hostState.parentObserver = null;
            }
            hostState.parentNode = null;
            if (hostState.detachTimeout) {
              clearTimeout(hostState.detachTimeout);
              hostState.detachTimeout = null;
            }
            hostState.domRefs = null;
            hostState.headerElms = null;
            hostState.subButtonEls = null;
          };

          const scheduleDetachPoll = () => {
            if (!hostState || hostState.detachTimeout) return;
            hostState.detachTimeout = setTimeout(() => {
              hostState.detachTimeout = null;
              if (!host?.isConnected) {
                cleanupHostResources();
                return;
              }
              scheduleDetachPoll();
            }, 60000);
          };

          const watchHostParent = () => {
            if (!hostState || !host?.parentNode) return;
            if (hostState.parentObserver && hostState.parentNode === host.parentNode) return;
            if (hostState.parentObserver) {
              hostState.parentObserver.disconnect();
              hostState.parentObserver = null;
            }
            hostState.parentNode = host.parentNode;
            const mo = new MutationObserver(records => {
              if (!host?.isConnected) {
                cleanupHostResources();
                return;
              }
              for (const record of records) {
                for (const removed of record.removedNodes) {
                  if (removed === host) {
                    cleanupHostResources();
                    return;
                  }
                }
              }
            });
            mo.observe(host.parentNode, { childList: true });
            hostState.parentObserver = mo;
          };

          watchHostParent();
          scheduleDetachPoll();

          const getState = id => (id && ha.states[id]) ? ha.states[id] : null;
          const batteryState = getState(batteryId);
          const rangeState = getState(rangeId);

          const subButtonColorCfg = Array.isArray(cfg.sub_button_colors) ? cfg.sub_button_colors : [];
          if (subButtonColorCfg.length && !hostState.subButtonEls) {
            hostState.subButtonEls = Array.from(container?.querySelectorAll('.bubble-sub-button') || []);
          }
          const subButtonEls = subButtonColorCfg.length ? hostState.subButtonEls : [];
          const subButtonStates = subButtonEls.map(el => getState(el.getAttribute('data-entity'))?.state ?? '');

          const rev = `${batteryState?.state ?? ''}|${batteryState?.last_updated ?? ''}|${rangeState?.state ?? ''}|${rangeState?.last_updated ?? ''}|${imageUrl}|${imageMaxWidth}|${subButtonStates.join(',')}`;

          const cacheKey = `bcev|${mainEntityId}`;
          const last = stateMem[cacheKey];
          const now = Date.now();
          const renderedRoot = host?.querySelector?.('.bc-ev');
          const isStale = !last || last.rev !== rev || !renderedRoot;

          if (!isStale) return;
          stateMem[cacheKey] = { rev, ts: now };
          pruneMemStore(stateMem, 12);

          let root = renderedRoot;
          if (!root) {
            root = document.createElement('div');
            root.className = 'bc-ev';
            root.innerHTML = `
              <div class="bc-ev-image"><img /></div>
              <div class="bc-ev-battery-row">
                <span class="bc-ev-percent"></span>
                <span class="bc-ev-range"></span>
              </div>
              <div class="bc-ev-bar-track"><div class="bc-ev-bar-fill"></div></div>
            `;
            host.appendChild(root);

            if (hostState && !hostState.resizeObserver) {
              const ro = new ResizeObserver(() => positionRoot());
              try { ro.observe(host); } catch {}
              hostState.resizeObserver = ro;
            }
            hostState.domRefs = null;
            hostState.headerElms = null;
            hostState.subButtonEls = null;
          }

          if (!hostState.domRefs) {
            hostState.domRefs = {
              img:     root.querySelector('.bc-ev-image img'),
              percent: root.querySelector('.bc-ev-percent'),
              range:   root.querySelector('.bc-ev-range'),
              fill:    root.querySelector('.bc-ev-bar-fill'),
            };
          }
          const { img, percent, range: rangeEl, fill } = hostState.domRefs;

          if (!hostState.headerElms) {
            hostState.headerElms = [elements?.iconContainer, elements?.name, elements?.state]
              .filter(Boolean);
          }

          const positionRoot = () => {
            if (!root) return;
            let headerBottom = 0;
            try {
              const hostRect = host.getBoundingClientRect();
              for (const elm of hostState.headerElms) {
                if (elm.offsetParent !== null) {
                  const rect = elm.getBoundingClientRect();
                  const bottom = rect.bottom - hostRect.top;
                  if (rect.height > 0 && bottom > headerBottom) headerBottom = bottom;
                }
              }
            } catch {}
            const hasSubButtons = !!container?.querySelector('.bubble-sub-button-bottom-container');
            root.style.top = `${Math.max(0, headerBottom + 6)}px`;
            root.style.bottom = hasSubButtons ? '44px' : '0';
          };
          requestAnimationFrame(positionRoot);

          if (img && img.getAttribute('src') !== imageUrl) img.setAttribute('src', imageUrl);
          if (img) img.style.setProperty('--bc-ev-image-max-width', imageMaxWidth || '100%');

          const socRaw = batteryState ? Number(batteryState.state) : NaN;
          const soc = isNaN(socRaw) ? null : Math.max(0, Math.min(100, socRaw));

          const rangeNum = rangeState ? Number(rangeState.state) : NaN;
          const rangeVal = rangeState ? (isNaN(rangeNum) ? rangeState.state : Math.round(rangeNum)) : '';
          const rangeUnit = rangeState?.attributes?.unit_of_measurement || '';

          percent.textContent = soc != null ? `${Math.round(soc)}%` : '--';
          rangeEl.textContent = rangeVal ? `${rangeVal} ${rangeUnit}` : '';

          fill.style.width = `${soc != null ? soc : 0}%`;

          const resolveUiColor = value => {
            if (!value || value === 'none') return null;
            return /^#|^rgb|^hsl|^var\(/i.test(value) ? value : `var(--${value}-color)`;
          };

          subButtonColorCfg.forEach(button => {
            const el = subButtonEls[button.index];
            if (!el) return;
            el.style.removeProperty('background-color');
            el.style.removeProperty('color');
            el.style.fontWeight = button.bold ? 'bold' : '';

            const currentState = (subButtonStates[button.index] || '').toLowerCase();
            const states = Array.isArray(button.states) ? button.states : [];
            const match = states.find(s => typeof s.state === 'string' && s.state.trim().toLowerCase() === currentState);
            if (!match) return;
            const bg = resolveUiColor(match.background);
            const fg = resolveUiColor(match.text_color);
            if (bg) el.style.setProperty('background-color', bg);
            if (fg) el.style.setProperty('color', fg);
          });
        })()}

    editor:
        - type: expandable
          title: Entities
          icon: mdi:car-electric
          schema:
            - name: image_url
              label: Car image URL
              selector:
                text: {}
            - name: battery_entity
              label: Battery level entity
              selector:
                entity:
                  domain: sensor
            - name: range_entity
              label: Range entity
              selector:
                entity:
                  domain: sensor
        - type: expandable
          title: Layout and styling
          icon: mdi:palette
          schema:
            - name: card_layout
              label: Card layout
              selector:
                select:
                  options:
                    - label: Default
                      value: default
                    - label: Square card
                      value: square
            - name: image_max_width
              label: Car image max width (e.g. 80% or 200px)
              selector:
                text: {}
            - name: card_min_height
              label: Minimum card height for default layout (e.g. 200px)
              selector:
                text: {}
        - type: expandable
          title: Sub-button colors
          icon: mdi:palette-swatch
          schema:
            - type: constant
              label: Colors a sub button by its own entity's state. Sub-button index is 0-based (first sub button = 0).
            - name: sub_button_colors
              label: Sub-button by index
              selector:
                object:
                  multiple: true
                  label_field: index
                  fields:
                    index:
                      label: Sub-button index
                      default: 0
                      required: true
                      selector:
                        number:
                          min: 0
                          step: 1
                          mode: box
                    bold:
                      label: Bold text
                      selector:
                        boolean: {}
                    states:
                      label: States
                      selector:
                        object:
                          multiple: true
                          label_field: state
                          fields:
                            state:
                              label: State to match (e.g. charging)
                              required: true
                              selector:
                                text: {}
                            background:
                              label: Background color
                              selector:
                                ui_color:
                                  include_none: true
                                  default_color: none
                            text_color:
                              label: Text color
                              selector:
                                ui_color:
                                  include_none: true
                                  default_color: none

---

Screenshot:

[koehntopp]

NICE!

Any idea why my image isn't shown at full size?

[jgvsaramago]

Hey, thanks! First I would suggest you cut your image to as close as possible to the car itself, and it would look nicer with transparent background. Then, unless you really want it like this, you can go to card settings and deactivate Show Icon and Show Entity State and you will get more free space for the image.

[koehntopp]

There should be enough space, I've already tried different image sizes, I just can't get it larger....

• type: custom:bubble-card
  card_type: button
  button_type: state
  entity: sensor.fordpass_soc
  name: Mustang
  modules:
  • ev_car_card
    ev_car_card:
    image_url: /local/cars/mustang.jpg
    battery_entity: sensor.fordpass_soc
    range_entity: sensor.fordpass_elveh
    card_layout: default
    card_min_height: 220px
    sub_button_colors:
    • index: 0
      bold: true
      states:
      • state: pv
        background: green
        text_color: white
    • index: 1
      bold: true
      states:
      • state: now
        background: amber
        text_color: white
        sub_button:
        main: []
        bottom:
    • tap_action:
      action: perform-action
      perform_action: select.select_option
      target:
      entity_id:
      - select.evcc_sap_alfen_mode
      data:
      option: pv
      show_name: false
      show_background: true
      icon: mdi:white-balance-sunny
      name: ' '
      scrolling_effect: false
      entity: sensor.mustang_lademodus_spiegel
    • tap_action:
      action: perform-action
      perform_action: select.select_option
      target:
      entity_id:
      - select.evcc_sap_alfen_mode
      data:
      option: now
      name: JETZT
      show_name: false
      icon: mdi:power-plug
      entity: sensor.mustang_lademodus_spiegel
      show_background: true
      scrolling_effect: false

[jgvsaramago]

The card was designed with an image of the car without empty padding around the car, as then the card has margins to the top and bottom so the car does not touch the title or battery bar. Can you send an screenshot of how it looks with the car image like I explained? Try using the image below.

[koehntopp]

That is actually better - THANK YOU!
I'll change my images accordingly...

[koehntopp]

(sorry to bother you - is there a way to make it fill the card? It's about 50% only now...)

[jgvsaramago]

What do you mean with fill the card? Having less space between the image and the text? Or just making the image bigger? If you want to adjust the image size you can change the card_min_height: 220px to a bigger value.