[JS+Editor Module] Icon border as progress indicator V2

[lsmarsden]

Icon Border Progress

Version: 1.7.0
Creator: lsmarsden

Important

Supported cards:

• button
• climate
• cover
• media-player
• pop-up
• select
• separator

Icon Border Progress

Forked from Nick's module.

    This module adds the ability to show progress of an entity via icon borders. If using a custom border-radius please make sure you define --bubble-icon-border-radius for this to work correctly.

    Also supports timers!
</p>

<p>
    For full documentation including configuration, examples, and more, visit the <a
        href="https://github.com/lsmarsden/bubble-card-modules/tree/main/modules/icon_border_progress"
        target="_blank">GitHub repo</a>.
</p>

---

🧩 Get this Module

To use this module, search for Icon Border Progress in the module store.
Alternatively, copy and paste the following configuration into your /www/bubble/bubble-modules.yaml file.

icon_border_progress:
  name: Icon Border Progress
  version: v1.7.0
  creator: lsmarsden
  link: https://github.com/lsmarsden/bubble-card-modules/tree/main/icon_border_progress
  supported:
    - button
    - climate
    - cover
    - media-player
    - pop-up
    - select
    - separator
  description: |-
    <div><h2>Icon Border Progress</h2>
        <p>
            Forked from <a href="https://github.com/Clooos/Bubble-Card/discussions/1296" target="_blank">Nick's module</a>.

            This module adds the ability to show progress of an entity via icon borders. If using a custom border-radius please make sure you define --bubble-icon-border-radius for this to work correctly.

            Also supports timers!
        </p>

        <p>
            For full documentation including configuration, examples, and more, visit the <a
                href="https://github.com/lsmarsden/bubble-card-modules/tree/main/modules/icon_border_progress"
                target="_blank">GitHub repo</a>.
        </p>
    </div>
  code: |-
    ${(() => {
    /**
     * ======== IMPORTED HELPER FUNCTIONS =========
     */

    const getState = (input, fallbackToRaw = true) => {
      if (input == null) return undefined;
      if (typeof input !== "string" && typeof input !== "object") return fallbackToRaw ? input : undefined;

      const entityDetails = parseEntity(input);
      const stateObj = hass.states[entityDetails.entityId];

      if (!stateObj) return fallbackToRaw ? input : undefined;

      return entityDetails.attribute ? stateObj.attributes[entityDetails.attribute] : stateObj.state;
    };

    const parseEntity = (input) => {
      let entityId, attribute;
      if (typeof input === "object" && input !== null) {
        entityId = input.entity_id || input.entity;
        attribute = input.attribute || input.att;
      }
      if (typeof input === "string") {
        // Pattern: entity_id[attribute]
        const match = input.match(/^([A-z0-9_.]+)\[([A-z0-9_]+)]$/);
        if (match) {
          [, entityId, attribute] = match;
        } else {
          entityId = input;
        }
      }
      return { entityId, attribute };
    };

    function checkAllConditions(cProp) {
      if (!cProp) return true;
      if (Array.isArray(cProp)) {
        return cProp.every((condition) => evaluateSingleCondition(condition));
      }
      return evaluateSingleCondition(cProp);
    }



    function evaluateSingleCondition(condObj) {
      if (!condObj || typeof condObj !== "object") return false;
      if (!condObj.condition) return false;
      const t = condObj.condition;
      switch (t) {
        case "state": {
          const state = getState(condObj, false);
          if (state === undefined) return false;
          if (Array.isArray(condObj.state)) {
            return condObj.state.includes(state);
          }
          return state === condObj.state;
        }
        case "numeric_state": {
          const numVal = parseFloat(getState(condObj));
          if (isNaN(numVal)) return false;

          const aboveVal = parseFloat(getState(condObj.above));
          if (!isNaN(aboveVal) && numVal <= aboveVal) {
            return false;
          }

          const belowVal = parseFloat(getState(condObj.below));
          if (!isNaN(belowVal) && numVal >= belowVal) {
            return false;
          }

          return true;
        }
        case "exists":
          return getState(condObj) !== undefined;
        case "and":
          if (!Array.isArray(condObj.conditions)) return false;
          return condObj.conditions.every((sc) => evaluateSingleCondition(sc));
        case "or":
          if (!Array.isArray(condObj.conditions)) return false;
          return condObj.conditions.some((sc) => evaluateSingleCondition(sc));
        case "not":
          if (Array.isArray(condObj.conditions) && condObj.conditions.length > 0) {
            return !evaluateSingleCondition(condObj.conditions[0]);
          }
          if (condObj.conditions) {
            return !evaluateSingleCondition(condObj.conditions);
          }
          return false;
        default:
          return false;
      }
    }


    function resolveColor(color, defaultColor) {
      let resolvedColor = getState(color);
      if (!resolvedColor) return defaultColor ?? "var(--primary-color)";
      if (typeof resolvedColor !== "string") return defaultColor ?? "var(--primary-color)";

      resolvedColor = resolvedColor.trim();
      const validPrefixes = ["#", "rgb", "hsl", "var(--"];

      if (validPrefixes.some((prefix) => resolvedColor.startsWith(prefix))) {
        return resolvedColor;
      }

      return `var(--${resolvedColor}-color)`;
    }



    function resolveColorFromStops(progress, stops, interpolate) {
      // handles the situation when HA reformats arrays into objects keyed by numbers.
      if (!Array.isArray(stops) && typeof stops === "object" && stops !== null) {
        stops = Object.values(stops).sort((a, b) => a.percent - b.percent);
      }
      if (!Array.isArray(stops) || !stops || stops.length === 0) {
        return "var(--primary-color)";
      }
      // Sort stops in ascending order by percent
      const sortedStops = stops.slice().sort((a, b) => a.percent - b.percent);

      // Handle out-of-range progress values
      if (progress <= sortedStops[0].percent) {
        return resolveColor(sortedStops[0].color);
      }
      if (progress >= sortedStops[sortedStops.length - 1].percent) {
        return resolveColor(sortedStops[sortedStops.length - 1].color);
      }

      // Find the lower and upper bounds
      const lower = [...sortedStops].reverse().find((s) => s.percent <= progress);
      const upper = sortedStops.find((s) => s.percent >= progress);

      if (!interpolate || resolveColor(lower.color) === resolveColor(upper.color)) {
        return resolveColor(lower.color);
      }

      const range = upper.percent - lower.percent;
      const frac = (progress - lower.percent) / range;
      const format = (v) => parseFloat(v.toFixed(2));

      return `color-mix(in srgb, ${resolveColor(lower.color)} ${format((1 - frac) * 100)}%, ${resolveColor(upper.color)} ${format(frac * 100)}%)`;
    }


    function applyEffects(element, effects) {
      Object.values(effects).forEach((eff) => {
        if (eff.effect) {
          if (checkAllConditions(eff.condition)) {
            element.classList.add(`progress-effect-${eff.effect}`, "has-effect");
          } else {
            element.classList.remove(`progress-effect-${eff.effect}`);
          }
        }
      });
    }


    function toArray(object) {
      if (Array.isArray(object)) return object;
      if (!object || typeof object !== "object") return [];

      return Object.values(object);
    }

    const resolveConfig = (sources, defaultValue = undefined) => {
      for (const source of sources) {
        const keys = Array.isArray(source.path) ? source.path : source.path.split(".");
        const value = getConfigValue(source.config, keys);

        if (value !== undefined && (!source.condition || source.condition(value, source.config))) {
          const metadata = source.metadata || {};
          if (metadata.deprecated) {
            console.warn(
              `[DEPRECATED] Config path "${source.path}" used.` +
                (metadata.replacedWith ? ` Use "${metadata.replacedWith}" instead.` : "") +
                (metadata.message ? ` ${metadata.message}` : ""),
            );
          }
          return value;
        }
      }
      return defaultValue;
    };

    function getConfigValue(config, keys) {
      let current = config;
      for (const key of keys) {
        if (current && key in current) {
          current = current[key];
        } else {
          return undefined;
        }
      }
      return current;
    }

    function detectElementShape(element, dimensions, borderRadiusOverride) {
      // Priority: config override > computed CSS > default
      let borderRadiusStyle;

      if (borderRadiusOverride !== undefined && borderRadiusOverride !== null) {
        // Convert number to px string, or use string as-is
        borderRadiusStyle =
          typeof borderRadiusOverride === "number" ? `${borderRadiusOverride}px` : String(borderRadiusOverride);
      } else {
        // Fall back to computed CSS
        borderRadiusStyle = getBorderRadiusStyle(element);
      }

      return detectShapeFromBorderRadius(borderRadiusStyle, dimensions);
    }

    function detectShapeFromBorderRadius(borderRadiusStyle, dimensions) {
      const { width, height } = dimensions;
      let borderRadius = 0;

      if (!borderRadiusStyle) {
        return { isCircular: false, borderRadius: 0 };
      }

      // Parse border radius value to pixels
      if (borderRadiusStyle.includes("%")) {
        const percent = parseInt(borderRadiusStyle) || 0;
        // For percentages, calculate actual pixel value
        // 50% of a 40px element = 20px border radius
        borderRadius = (percent / 100) * Math.min(width, height);
      } else {
        // For pixel values, just parse the number
        borderRadius = parseInt(borderRadiusStyle) || 0;
      }
      const isCircular = width === height && borderRadius >= width / 2;

      return { isCircular, borderRadius };
    }

    function getBorderRadiusStyle(element) {
      if (typeof getComputedStyle === "undefined") {
        return "";
      }

      const computedStyle = getComputedStyle(element);
      return computedStyle.borderRadius || "";
    }

    function createProgressBorder(element, progressValue, progressColor, remainingColor, options) {
      const { strokeWidth = 3, animationDuration = 800, borderRadiusOverride, offsetPercent = 0 } = options;
      progressValue = Math.max(0, Math.min(100, progressValue || 0));
      const clampedOffsetPercent = Math.max(0, Math.min(100, offsetPercent));

      let svg = element.querySelector(".stroke-dash-aligned-svg");

      if (!svg) {
        const computedStyle = typeof getComputedStyle !== "undefined" ? getComputedStyle(element) : {};
        if (computedStyle.position === "static") {
          element.style.position = "relative";
        }

        svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
        svg.setAttribute("class", "stroke-dash-aligned-svg");
        svg.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none";
        element.appendChild(svg);
      }

      const dimensions = getEffectiveDimensions(element);
      svg.setAttribute("viewBox", `0 0 ${dimensions.width} ${dimensions.height}`);
      svg.style.width = `${dimensions.width}px`;
      svg.style.height = `${dimensions.height}px`;

      // Detect shape from border-radius CSS property using helper
      const { isCircular, borderRadius } = detectElementShape(element, dimensions, borderRadiusOverride);

      // Check if SVG needs rebuilding
      const existingPath = svg.querySelector(".progress-path");
      const currentData = `${isCircular}-${borderRadius}-${dimensions.width}-${dimensions.height}`;
      const storedData = svg.getAttribute("data-config");

      if (!existingPath || currentData !== storedData) {
        // Rebuild SVG
        svg.innerHTML = "";
        svg.setAttribute("data-config", currentData);

        // Create path data using actual dimensions
        const { width, height } = dimensions;
        let pathData;

        if (isCircular) {
          // For circles, use the smaller dimension as radius - start at top center
          const radius = (Math.min(width, height) - strokeWidth) / 2;
          const centerX = width / 2;
          pathData = `M ${centerX} ${strokeWidth / 2} A ${radius} ${radius} 0 1 1 ${centerX - 0.01} ${strokeWidth / 2}`;
        } else {
          const r = Math.min(borderRadius, (Math.min(width, height) - strokeWidth) / 2);
          const x = strokeWidth / 2;
          const y = strokeWidth / 2;
          const w = width - strokeWidth;
          const h = height - strokeWidth;

          if (r > 0) {
            // Rounded rectangle - start from top center
            const startX = width / 2;
            pathData = `M ${startX} ${y} 
                        L ${x + w - r} ${y} 
                        Q ${x + w} ${y} ${x + w} ${y + r} 
                        L ${x + w} ${y + h - r} 
                        Q ${x + w} ${y + h} ${x + w - r} ${y + h} 
                        L ${x + r} ${y + h} 
                        Q ${x} ${y + h} ${x} ${y + h - r} 
                        L ${x} ${y + r} 
                        Q ${x} ${y} ${x + r} ${y} 
                        L ${startX} ${y}`;
          } else {
            // Sharp rectangle - start from top center
            const startX = width / 2;
            pathData = `M ${startX} ${y} L ${x + w} ${y} L ${x + w} ${y + h} L ${x} ${y + h} L ${x} ${y} Z`;
          }
        }

        // Create background and progress paths
        ["bg-path", "progress-path"].forEach((className, index) => {
          const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
          path.setAttribute("class", className);
          path.setAttribute("d", pathData);
          path.setAttribute("stroke", index ? "transparent" : remainingColor); // Start progress path as transparent
          path.setAttribute("stroke-width", strokeWidth);
          path.setAttribute("fill", "none");

          if (index) {
            // progress path
            path.setAttribute("stroke-linecap", "round");
            path.style.transition = `all ${animationDuration}ms ease-out`;
          }

          svg.appendChild(path);
        });

        // Calculate path metrics
        const progressPath = svg.querySelector(".progress-path");
        const pathLength = progressPath.getTotalLength ? progressPath.getTotalLength() : 300; // Fallback for environments without getTotalLength

        progressPath.setAttribute("data-length", pathLength);
      }

      // Update progress
      const bgPath = svg.querySelector(".bg-path");
      const progressPath = svg.querySelector(".progress-path");

      bgPath.setAttribute("stroke", remainingColor);

      // Apply progress
      const pathLength = parseFloat(progressPath.getAttribute("data-length"));
      const progressLength = (progressValue / 100) * pathLength;
      const offsetLength = (clampedOffsetPercent / 100) * pathLength;

      // Check if this is the first time setting a non-zero progress value
      const wasTransparent = progressPath.getAttribute("stroke") === "transparent";
      const isFirstPositiveProgress = wasTransparent && progressValue > 0;

      if (progressValue <= 0) {
        // Make progress invisible when 0 or less - keeps transitions working
        progressPath.setAttribute("stroke", "transparent");
        progressPath.setAttribute("stroke-dasharray", `0 ${pathLength}`);
        progressPath.setAttribute("stroke-dashoffset", "0");
      } else {
        // Show progress path with proper color
        progressPath.setAttribute("stroke", progressColor);
        progressPath.setAttribute("stroke-dashoffset", "0"); // Always 0 with new offset approach

        const getDashArray = () => {
          if (progressValue >= 100) {
            return `${pathLength} 0`;
          } else if (progressLength === 0) {
            return `0 ${pathLength}`;
          } else if (offsetLength + progressLength <= pathLength) {
            // No wrap-around needed
            // Pattern: [transparent offset] [progress] [remaining transparent]
            return `0 ${offsetLength} ${progressLength} ${pathLength - offsetLength - progressLength}`;
          } else {
            // Wrap-around needed
            const endProgress = pathLength - offsetLength;
            const wrapProgress = progressLength - endProgress;
            // Pattern: [wrap progress] [gap] [main progress] [remaining]
            return `${wrapProgress} ${offsetLength - wrapProgress} ${endProgress} 0`;
          }
        };

        if (isFirstPositiveProgress) {
          // Start from 0 and animate to target on first appearance
          progressPath.setAttribute("stroke-dasharray", `0 ${offsetLength} 0 ${pathLength - offsetLength}`);
          progressPath.getBoundingClientRect();
          requestAnimationFrame(() => {
            progressPath.setAttribute("stroke-dasharray", getDashArray());
          });
        } else {
          progressPath.setAttribute("stroke-dasharray", getDashArray());
        }
      }
    }



    function getEffectiveDimensions(element) {
      if (!element || !element.getBoundingClientRect) {
        return { width: 38, height: 38 };
      }

      const rect = element.getBoundingClientRect();
      const width = rect.width || 38;
      const height = rect.height || 38;

      return { width, height };
    }



    const getDashArray = () => {
          if (progressValue >= 100) {
            return `${pathLength} 0`;
          } else if (progressLength === 0) {
            return `0 ${pathLength}`;
          } else if (offsetLength + progressLength <= pathLength) {
            // No wrap-around needed
            // Pattern: [transparent offset] [progress] [remaining transparent]
            return `0 ${offsetLength} ${progressLength} ${pathLength - offsetLength - progressLength}`;
          } else {
            // Wrap-around needed
            const endProgress = pathLength - offsetLength;
            const wrapProgress = progressLength - endProgress;
            // Pattern: [wrap progress] [gap] [main progress] [remaining]
            return `${wrapProgress} ${offsetLength - wrapProgress} ${endProgress} 0`;
          }
        };

    function removeProgressBorder(element) {
      const svg = element.querySelector(".stroke-dash-aligned-svg");
      if (svg) {
        svg.remove();
      }
    }

    const getAttributes = (input) => {
      if (input == null) return undefined;
      if (typeof input !== "string" && typeof input !== "object") return undefined;

      const entityDetails = parseEntity(input);
      const stateObj = hass.states[entityDetails.entityId];

      if (!stateObj) return undefined;
      return stateObj.attributes || {};
    };

    const getDomain = (input) => {
      if (input == null) return undefined;
      if (typeof input !== "string" && typeof input !== "object") return undefined;

      const entityDetails = parseEntity(input);
      return entityDetails.entityId ? entityDetails.entityId.split(".")[0] : undefined;
    };

    function parseHHMMSSToSeconds(timeString) {
      if (!timeString || typeof timeString !== "string") return 0;

      const parts = timeString.split(":");
      if (parts.length !== 3) return 0;

      const [hours, minutes, seconds] = parts.map(Number);
      if (isNaN(hours) || isNaN(minutes) || isNaN(seconds)) return 0;

      return hours * 3600 + minutes * 60 + seconds;
    }

    function calculateProgressValue(progressSource, progressOptions = { start: 0, end: 100 }) {
      // Check if this is a timer entity
      const domain = getDomain(progressSource);
      if (domain === "timer") {
        return calculateTimerProgress(progressSource);
      }

      // Existing numeric progress calculation
      let progressValue = parseFloat(getState(progressSource));
      let startValue = parseFloat(getState(progressOptions.start));
      let endValue = parseFloat(getState(progressOptions.end));

      startValue = isNaN(startValue) ? 0 : startValue;
      endValue = isNaN(endValue) ? 100 : endValue;

      if (isNaN(progressValue) || progressValue < startValue) {
        progressValue = startValue;
      }
      if (progressValue > endValue) {
        progressValue = endValue;
      }

      return ((progressValue - startValue) / (endValue - startValue)) * 100;
    }

    function calculateTimerProgress(timer) {
      const timerState = getState(timer);
      const attributes = getAttributes(timer);

      if (!timerState || !attributes) {
        return 0;
      }

      if (timerState === "active") {
        // Calculate progress based on current time, duration, and finishes_at
        const duration = attributes.duration;
        const finishesAt = attributes.finishes_at;

        if (!duration || !finishesAt) return 0;

        const durationSeconds = parseHHMMSSToSeconds(duration);
        const finishTime = new Date(finishesAt);
        const currentTime = new Date();

        if (durationSeconds === 0) return 0;

        // Calculate remaining time and then elapsed time
        const remainingSeconds = (finishTime.getTime() - currentTime.getTime()) / 1000;
        const elapsedSeconds = durationSeconds - remainingSeconds;

        // Clamp between 0 and 100%
        return Math.max(0, Math.min(100, (elapsedSeconds / durationSeconds) * 100));
      } else if (timerState === "paused") {
        // Calculate progress based on duration and remaining
        const duration = attributes.duration;
        const remaining = attributes.remaining;

        if (!duration || !remaining) return 0;

        const durationSeconds = parseHHMMSSToSeconds(duration);
        const remainingSeconds = parseHHMMSSToSeconds(remaining);

        if (durationSeconds === 0) return 0;

        const elapsedSeconds = durationSeconds - remainingSeconds;
        return Math.max(0, Math.min(100, (elapsedSeconds / durationSeconds) * 100));
      }

      // All other states (idle, finished, etc.) return 0
      return 0;
    }

    function isActiveTimer(progressSource) {
      return isTimerEntity(progressSource) && getState(progressSource) === "active";
    }

    function isTimerEntity(progressSource) {
      return getDomain(progressSource) === "timer";
    }

    function manageTimerUpdater(element, progressSource, updateFn) {
      const hasUpdater = !!element.dataset.progress_update_interval;
      const shouldHaveUpdater = isActiveTimer(progressSource);

      if (shouldHaveUpdater && !hasUpdater) {
        element.dataset.progress_update_interval = setInterval(updateFn, 1000);
      }

      if (!shouldHaveUpdater && hasUpdater) {
        clearInterval(Number(element.dataset.progress_update_interval));
        element.removeAttribute("data-progress_update_interval");
      }
    }

    /**
     * ======== MAIN MODULE CODE =========
     */


      // this allows IDEs to parse the file normally - will be removed automatically during build.
      const { icon_border_progress: config } = this.config;

      function getElementSelector(button) {
        if (button === "main-button" || button === "main") {
          return ".bubble-icon-container";
        } else {
          return `.bubble-${button}`;
        }
      }

      function storeOriginalBackground(element) {
        if (element.dataset.originalBackground === undefined) {
          element.dataset.originalBackground = element.style.background || "";
        }
      }

      function cleanupProgressStyling(element) {
        element.style.background = element.dataset.originalBackground;

        removeProgressBorder(element);
      }

      function resolveColorConfigs(buttonConfig) {
        const remainingColor = resolveConfig([
          { config: buttonConfig, path: "remaining_color" },
          {
            config: buttonConfig,
            path: "remainingcolor",
            metadata: { deprecated: true, replacedWith: "remaining_color" },
          },
        ]);

        const backColor = resolveConfig([
          { config: buttonConfig, path: "background_color" },
          {
            config: buttonConfig,
            path: "backcolor",
            metadata: { deprecated: true, replacedWith: "background_color" },
          },
        ]);

        return {
          remainingProgressColor: resolveColor(remainingColor, "var(--dark-grey-color)"),
          backgroundColor: resolveColor(backColor, "var(--bubble-icon-background-color)"),
          hasBackgroundColor: backColor !== undefined && backColor !== null,
        };
      }

      function applyProgressStyling(element, progressValue, progressColor, colors, buttonConfig) {
        // Only set background if one was configured
        // This allows us to pass-through colours that Bubble Card sets automatically
        // e.g. colours based on the light entity
        if (colors.hasBackgroundColor) {
          element.style.background = `${colors.backgroundColor}`;
        }
        element.style.position = "relative"; // Ensure element can contain absolutely positioned SVG

        createProgressBorder(element, progressValue, progressColor, colors.remainingProgressColor, {
          strokeWidth: 3,
          animationDuration: 800,
          borderRadiusOverride: buttonConfig?.border_radius,
          offsetPercent: buttonConfig?.offset_percent || 0,
        });
      }

      function updateProgressDisplay(progressSource, buttonConfig, buttonElement) {
        const progressValue = calculateProgressValue(progressSource, buttonConfig);
        const inverted = buttonConfig?.invert || false;
        const adjustedProgress = inverted ? 100 - progressValue : progressValue;
        const colorStops = buttonConfig.color_stops || [];
        const progressColor = resolveColorFromStops(adjustedProgress, colorStops, buttonConfig.interpolate_colors);
        const colors = resolveColorConfigs(buttonConfig);

        applyProgressStyling(buttonElement, adjustedProgress, progressColor, colors, buttonConfig);
      }

      // group button configs by button name
      function groupByButton(configArray) {
        return configArray.reduce((groups, buttonConfig) => {
          const button = buttonConfig.button;
          if (!button) return groups;

          if (!groups.has(button)) {
            groups.set(button, []);
          }
          groups.get(button).push(buttonConfig);
          return groups;
        }, new Map());
      }

      // Main processing loop
      groupByButton(toArray(config)).forEach((buttonConfigs, button) => {
        const selector = getElementSelector(button);
        const buttonElement = card.querySelector(selector);
        if (!buttonElement) return;

        storeOriginalBackground(buttonElement);

        // Find the first configuration with matching conditions
        const matchingConfig = buttonConfigs.find((config) => checkAllConditions(config.condition));

        if (!matchingConfig) {
          // No matching conditions found, cleanup styling
          cleanupProgressStyling(buttonElement);
          const updateIntervalId = buttonElement.dataset.progress_update_interval;
          if (updateIntervalId) {
            buttonElement.removeAttribute("data-progress_update_interval");
            clearInterval(Number(updateIntervalId));
          }
          return;
        }

        const progressSource = resolveConfig([
          {
            config: matchingConfig,
            path: "source",
          },
          {
            config: matchingConfig,
            path: "entity",
            metadata: { deprecated: true, replacedWith: "source" },
          },
        ]);

        manageTimerUpdater(buttonElement, progressSource, () => {
          updateProgressDisplay(progressSource, matchingConfig, buttonElement);
        });
        updateProgressDisplay(progressSource, matchingConfig, buttonElement);
        applyEffects(buttonElement, matchingConfig.effects || []);
      });
    })()}

    :root {
        --animated-progress-stroke-width: 3;
        --animated-progress-transition-duration: 0.3s;
        --bubble-border-inset: 2px;
    }

    .bubble-icon-container {
        container-type: size;
    }

    .progress-border {
        position: relative;
    }

    .animated-mask-svg {
        position: absolute;
        top: 0;
        left: 0;
        pointer-events: none;

        /* Performance optimizations */
        contain: layout style paint;
        transform: translateZ(0);
        /* Force hardware acceleration */
    }

    .mask-sector {
        fill: black;
        transition: d var(--animated-progress-transition-duration) cubic-bezier(0.4, 0, 0.2, 1);
        will-change: d;
        contain: layout style paint;
    }

    .bg-path,
    .progress-path {
        fill: none;
        stroke-width: var(--animated-progress-stroke-width, 3);
        stroke-linecap: round;
        transition: all var(--animated-progress-transition-duration, 0.3s) cubic-bezier(0.4, 0, 0.2, 1);
        will-change: stroke;
    }
  editor:
    - type: expandable
      title: Dynamic Entity Resolution
      icon: mdi:information-variant-circle-outline
      schema:
        - type: constant
          label: Dynamic Entity Resolution (DER)
          value: >-
            If you see ✨ in an input field, then it supports DER. This allows entry of an entity, attribute, or regular
            value. Just enter the entity name. For attributes, use the format ENTITY[ATTRIBUTE], e.g.,
            sensor.my_phone[battery_level].
    - type: expandable
      name: '0'
      title: Icon 1 settings (define more in YAML)
      schema:
        - name: button
          label: Button to apply to. Use 'main' or 'sub-button-1' etc.
          selector:
            text: null
        - name: source
          label: ✨Source entity
          selector:
            entity: {}
        - name: invert
          label: Invert the progress direction
          selector:
            boolean:
              default: false
        - name: condition
          label: Condition to show progress (see docs for additional condition configuration)
          selector:
            condition: {}
        - type: expandable
          label: Custom start/end values (optional)
          schema:
            - type: constant
              value: Use these to override the default 0-100 progress range.
            - name: start
              label: ✨Start value of entity
              selector:
                number:
                  default: 0
            - name: end
              label: ✨End value of entity
              selector:
                number:
                  default: 100
        - name: border_radius
          label: Border radius override (e.g., 10 for 10px, or '50%' for circular)
          selector:
            text: null
        - type: expandable
          label: Color settings
          schema:
            - name: interpolate_colors
              label: Gradually transition between colours
              selector:
                boolean: null
            - type: expandable
              name: color_stops
              label: Progress colors - add more in YAML
              schema:
                - type: expandable
                  label: Color 1
                  name: '0'
                  schema:
                    - name: color
                      label: ✨Color
                      selector:
                        ui_color: null
                    - name: percent
                      label: From %
                      selector:
                        number:
                          min: 0
                          max: 100
                          step: 1
                          unit_of_measurement: '%'
                - type: expandable
                  label: Color 2
                  name: '1'
                  schema:
                    - name: color
                      label: ✨Color
                      selector:
                        ui_color: null
                    - name: percent
                      label: From %
                      selector:
                        number:
                          min: 0
                          max: 100
                          step: 1
                          unit_of_measurement: '%'
            - name: background_color
              label: ✨Background colour of icon
              selector:
                ui_color: null
            - name: remaining_color
              label: ✨Color of remaining progress section
              selector:
                ui_color: null
    - type: expandable
      name: '1'
      title: Icon 2 settings (define more in YAML)
      schema:
        - name: button
          label: Button to apply to. Use 'main' or 'sub-button-1' etc.
          selector:
            text: null
        - name: source
          label: ✨Source entity
          selector:
            entity: {}
        - name: invert
          label: Invert the progress direction
          selector:
            boolean:
              default: false
        - name: condition
          label: Condition to show progress (see docs for additional condition configuration)
          selector:
            condition: {}
        - type: expandable
          label: Custom start/end values (optional)
          schema:
            - type: constant
              value: Use these to override the default 0-100 progress range.
            - name: start
              label: ✨Start value of entity
              selector:
                number:
                  default: 0
            - name: end
              label: ✨End value of entity
              selector:
                number:
                  default: 100
        - name: border_radius
          label: Border radius override (e.g., 10 for 10px, or '50%' for circular)
          selector:
            text: null
        - type: expandable
          label: Color settings
          schema:
            - name: interpolate_colors
              label: Gradually transition between colours
              selector:
                boolean: null
            - type: expandable
              name: color_stops
              label: Progress colors - add more in YAML
              schema:
                - type: expandable
                  label: Color 1
                  name: '0'
                  schema:
                    - name: color
                      label: ✨Color
                      selector:
                        ui_color: null
                    - name: percent
                      label: From %
                      selector:
                        number:
                          min: 0
                          max: 100
                          step: 1
                          unit_of_measurement: '%'
                - type: expandable
                  label: Color 2
                  name: '1'
                  schema:
                    - name: color
                      label: ✨Color
                      selector:
                        ui_color: null
                    - name: percent
                      label: From %
                      selector:
                        number:
                          min: 0
                          max: 100
                          step: 1
                          unit_of_measurement: '%'
            - name: background_color
              label: ✨Background colour of icon
              selector:
                ui_color: null
            - name: remaining_color
              label: ✨Color of remaining progress section
              selector:
                ui_color: null

---

Screenshot:

Before posting your module

• I've replaced all lines starting with ->
• I've updated the unsupported cards above the description and under the unsupported property
• I've added a screenshot
• I've chosen a unique your_module_key
• I really enjoyed working on this module ❤️

[Psix-anp]

Hi, only gray

[lsmarsden]

Hi, could you please paste the full YAML so I can try and reproduce this?

[Psix-anp]

Okay

type: custom:bubble-card
card_type: button
button_type: switch
entity: vacuum.siaomik
icon_border_progress:

• button: main
  source: sensor.siaomik_battery_level
  color_stops:
  "0":
  color: orange
  percent: 30
  "1":
  color: green
  percent: 70
  interpolate_colors: true
  modules:
• icon_border_progress
  sub_button:
• entity: sensor.siaomik_battery_level
  show_state: true
  show_background: false
  button_action:
  tap_action:
  action: navigate
  navigation_path: /dashboard-main/vacuumm40

[lsmarsden]

Thanks - that helped me figure out the problem. I had a slight bug with the editor using source in the YAML but the YAML was expecting entity instead.

I've fixed that in v1.0.2 which you can download in the module store now. Your code should start working as soon as you install the update without any changes required.

Sorry about that! Let me know if you have any issues.

[Psix-anp]

Thnx, working!!

[Krusenbaum]

Very nice module but unfortunately does not work with any other border radius configured. Example: the system will look really weird on a system with "bubble-border-radius: '12px'".

[lsmarsden]

Hi, sorry for the delay on this. Yes this is a funky issue because of the original design and using a radial-gradient. I'm looking into making this much more flexible at the moment.

[lsmarsden]

Hey, I've made a pretty big change under the hood at how the progress border is created. This should be fixed now in v1.2.0! It should now automatically match the border radius (if not, you can provide a custom border_radius value per button) Could you give it a try and let me know how it goes?

[chicco-carone]

I was trying to use this module to put on the icon for the media player card the volume for the media player but I can't manage to tell the module to pull the value from the volume attribute from the media player. I set the source value as the media player entity and overwrote the values since media players go from 0 to 1 without success

[chicco-carone]

It's not working for me the volume is at half and still nothing, i tried also replacing the image with just the icon and its not visible

[lsmarsden]

Strange, can you go to Dev tools > Template and check the attributes on your media player entity? I'm wondering if it's a language difference.

If you check the output of the template {{ states['media_player.pranzo'].attributes }} this should give all attributes. If something related to volume_level is there, that should work. If not, feel free to drop the attribute output here.

Here's an example of mine:

[chicco-carone]

I can see the volume level in mine too, here is the output:
{'group_members': ['media_player.chicco_ma', 'media_player.pranzo', 'media_player.letto'], 'volume_level': 0.16, 'is_volume_muted': False, 'media_content_id': 'library://track/557', 'media_content_type': <MediaType.MUSIC: 'music'>, 'media_duration': 944, 'media_position': 540, 'media_position_updated_at': datetime.datetime(2025, 6, 27, 12, 21, 11, 461062, tzinfo=datetime.timezone.utc), 'media_title': 'Chameleon (Album Version)', 'media_artist': 'Herbie Hancock', 'media_album_name': 'Head Hunters', 'media_album_artist': 'Herbie Hancock', 'app_id': 'music_assistant', 'shuffle': False, 'repeat': 'off', 'mass_player_type': 'player', 'active_queue': 'ma_fc15b4ebd55c', 'device_class': 'speaker', 'entity_picture': '/api/media_player_proxy/media_player.pranzo?token=token&cache=254dc824ba440d80', 'icon': 'mdi:speaker', 'friendly_name': 'Pranzo', 'supported_features': <MediaPlayerEntityFeature.PAUSE|SEEK|VOLUME_SET|VOLUME_MUTE|PREVIOUS_TRACK|NEXT_TRACK|PLAY_MEDIA|VOLUME_STEP|STOP|CLEAR_PLAYLIST|PLAY|SHUFFLE_SET|BROWSE_MEDIA|REPEAT_SET|GROUPING|MEDIA_ANNOUNCE|MEDIA_ENQUEUE|SEARCH_MEDIA: 8320575>}
My media player has more attributes since its from music assistant but I don't think that's the issue

[lsmarsden]

This one is stumping me... I'm trying to replicate this but not having any luck. I just released v1.2.0, so there may be a chance it is fixed in there. Can you let me know if it's still an issue on that version?

[chicco-carone]

I just tried after updating and it's working great. Thanks for the help

[rekenaar00]

Hi, is it possible to adjust the size of the border on a sub-button that contains icon and state?

[lsmarsden]

Good find! Working on this at the moment. After looking deeper, this is actually a broader issue with general sub buttons of varying sizes. It might take some time!

[lsmarsden]

Hi, this should be fixed in v1.3.0 (ready to update in the module store) - let me know if it looks any better!

[rekenaar00]

Hi, is it possible to adjust the size of the border on a sub-button that contains icon and state?

fixed, thanks a lot

[simenopsahl]

When using it to show light brightness is there a way to pass through or inherit the background color for the light?

Or even to use the lights color as the remaining_color.

icon_border_progress:
  - button: sub-button-1
    source: light.floor1_kitchen[brightness]
    start: 0
    end: 255

[lsmarsden]

Just clarifying the use case - do you want to set the progress colour to the actual current colour of the bulb? Or are you looking for something else?

[simenopsahl]

I want the background to be the color of the bulb, like the row below.

[lsmarsden]

Ah, got it. I just took a look inside Bubble card itself - I didn't realise it had a lot of custom logic for dealing with lights and setting the background colours like that. I was defaulting to a background colour even if it wasn't in the YAML, which was overriding these.

If you update to v1.3.1 (in the module store now) it should just work straight away. This should be the pass-through you were referring to.

Thanks for raising this one!

[simenopsahl]

Excellent :)
Now it looks great

[lsmarsden]

Changelog

v1.3.0

• Removed start_angle configuration option, as it no longer makes sense with varying sizes.
  This will be superseded by a new option to offset the starting point in the future.
• Fixed border shape for buttons that are not always square/circular.

[lsmarsden]

Changelog

v1.3.1

• Use Bubble Card's automatic background colours when background_color is not set, instead of defaulting to
  var(--bubble-icon-background-color).
  This fixes background colours based on entity states.

[waffenpanter]

I have some Problems with my Cover, it dosnt work, can u help me pls?

thanks a lot

type: custom:bubble-card
card_type: cover
entity: cover.wohnstube_tur
show_icon: true
show_attribute: true
force_icon: false
scrolling_effect: false
rows: "1"
card_layout: large
attribute: current_position
modules:

• my_module
• icon_border_progress
  cover_gradient_background_indicator:
  color: blue-grey
  inverted: false
  show_state: true
  icon_border_progress:
• remaining_color: light-blue
  button: main
  interpolate_colors: false
  color_stops:
  "0":
  percent: 0
  "1":
  percent: 100
  source: cover.wohnstube_tur
  start: 0
  end: 100
  background_color: black
• interpolate_colors: false

[waffenpanter]

ah i have the sollution with source: cover.wohnstube_tur[current_position])

[zyi840449]

Can I set 2 progress circle for the same icon?
For example, in case A, the data source is entity A, and a blue progress circle is displayed.
In case B, the data source is entity B, and a yellow progress circle is displayed.

[zyi840449]

Project progress update:
I can use conditional settings to display a progress circle when case A or case B is true.
I can use my own defined sensors to integrate the data of entity A and entity B and use this as the data sources.

But I can't think of a way to dynamically change the color of the progress circle
(I mean, blue when input_boolean.A is turned on, red when input_boolean.B is turned on, etc.)

Perhaps you can consider supporting the use of variables for color settings?
For example, color: var(--my_color_red)

[lsmarsden]

You read my mind! I just had the thought to support variables in colours as well! It was a quick addition, so is now available in v1.4.0.

As for your use case in general, it could be simpler to have two identical sub-buttons with different progress module configurations.
One sub button can have the blue progress circle config, and the other has the yellow config. Then use a conditional on each sub-button to display only one in each of your cases (assuming they are mutually exclusive).
If you want some generic number of progress circle configs, this could get pretty chunky though. Let me know if the var() solution works for you!

[zyi840449]

You read my mind! I just had the thought to support variables in colours as well! It was a quick addition, so is now available in v1.4.0.

As for your use case in general, it could be simpler to have two identical sub-buttons with different progress module configurations. One sub button can have the blue progress circle config, and the other has the yellow config. Then use a conditional on each sub-button to display only one in each of your cases (assuming they are mutually exclusive). If you want some generic number of progress circle configs, this could get pretty chunky though. Let me know if the var() solution works for you!

Your code is useful. I have completed the desired function. It is not complicated.

The timing of progress circle appears: Use conditional expressions to trigger when event A or event B occurs.
Source: Define a sensor and use different rules to calculate the value according to different situations.
Color: Since it supports variables, just use conditions to change the value in the variable.

[lsmarsden]

Changelog

v1.4.0

• Added support for colours to be resolved using var(--my-custom-variable) in all ✨DER colour fields.

[Normanras]

Thanks @lsmarsden for the great module! I'm on the latest 1.4.0 version but having some trouble with integers and floats. I see your code above and it looks like it should take it into account, but since updating, it's not working. I was previously on 1.1.2 and that worked for all but one of my sensors, but now on 1.4.0, the progress bar only shows up for integers.

Here's an example of sensors and my dashboard yaml:

Let me know if I missed anything? I was trying to figure out the daily rain progress border not working for values between 0 and 2 (with the stops being 0.0, 0.2, 0.4, 0.6, etc but then after updating it seems like no floats are working.

I should add that I also tried 0.0 to 100.0 along with changing the color stops to floats in the exact format/decimal points that I see in the templates, but that didn't change anything. I also left the start and end as integers and only changes color stops to floats, but that also yielded no change.

I'll also try testing this with other sensors that are floats and see if there is some other consistency.

[lsmarsden]

Good testing! Thanks for the info. After having a look, the only issue I found related to floats is that the start and end configuration values were being parsed as ints instead of floats. This meant that there were some problems if using a float for those.

This should be fixed in v1.4.1 - let me know if you are still seeing issues!

The source entity should already support parsing floats, I double-checked this with some entities that report float states and it seemed to work properly.

For color stops, they should also support floats - but note that they have to be percent values of the total progress range, not absolute values. For your rain progress border ranging from 0 to 2, the color stops should use percent values of 10, 20, 30, ... instead of 0.2, 0.4, 0.6,.... I have thought about being able to use absolute values in color stops (to remove the need for the user to do manual calculations), but I haven't looked into it at all yet.

[Normanras]

Thank you!! Finally got around to updating and testing everything and it is working much more smoothly! Appreciate your quick reply.

[lsmarsden]

Changelog

v1.4.1

• Fixed issue where start and end values were not working with float values.

[lsmarsden]

Changelog

v1.5.0

• Added support for timer entities as source. Timers will ignore custom start and end values.

[BerrisNO]

Is it possible to add a max sensor instead of typing in s manual value ?

[lsmarsden]

Is this for the start and end options? If so, yes - just enter the sensor name into the field. If you're using the UI editor, any field with ✨ can do this. You can use:

• Simple values e.g. 0
• Entities e.g. input_text.my_favourite_color or sensor.max_sensor
• Attributes using format entity[attribute], such as sensor.my_sensor[max_attribute]

Check out more information here.

[BerrisNO]

Thanks!

[CykloneFij]

Thanks for this, works great, except when using with auto-entities template for some odd reason.
If I have this code in place it works fine:

          {%-for fan in state_attr('sensor.number_fans_on','entities') %}
            {%- if fan == 'fan.smart_plug_nomad_switch_2' %}
            {{
              {
                'type': 'custom:bubble-card',
                'card_type': 'button',
                'card_layout': 'normal',
                'entity': fan,
                'show_state': false,
                'modules': [
                  'progress_border_timer'
                ],
                'show_last_changed': true
              }
            }},
            {% else %}
            .....

But when I add the parameters for the module, it no longer displays:

          {%-for fan in state_attr('sensor.number_fans_on','entities') %}
            {%- if fan == 'fan.smart_plug_nomad_switch_2' %}
            {{
              {
                'type': 'custom:bubble-card',
                'card_type': 'button',
                'card_layout': 'normal',
                'entity': fan,
                'show_state': false,
                'modules': [
                  'progress_border_timer'
                ],
                'progress_border_timer': {
                  'circle_color': 'green',
                  'entity': timer.basement_fan
                },
                'show_last_changed': true
              }
            }},
            {% else %}
            .....

Somehow adding the 4 lines after the modules block breaks it.
I have other modules, badges for example, with same auto-entities template that work fine.
Cheers

[lsmarsden]

Hi, the module ID is icon_border_progress but your snippet is using progress_border_timer. For this module, the section should look something like this:

  'modules': [
    'icon_border_progress'
  ],
  'icon_border_progress': {
    'button': 'main',
    'background_color': 'green',
    'source': timer.basement_fan
  }

Let me know if that works at all. Check out some example YAML for the module or the schema config options for any other properties.

[CykloneFij]

@lsmarsden Thank you. Yes, I realised I was using an older module that did similar and mixed up the code. I tried the code you suggested but it doesn't work when I add the 'icon_border_progress` ': { ... } section, with just the modules: declaration it's fine of course.
From what I can tell in the yaml, each button is a group, so using [ ] brackets then the button:

                'icon_border_progress': [     <----
                  {
                    'button': 'main',
                    'remaining_color': 'green',
                    'source': timer.basement_fan,
                    'invert': false,
                    'condition': [
                      {
                        'condition': 'state',
                        'entity_id': timer.basement_fan,
                        'state': 'active'
                      }
                    ]
                  }
                ],          <----

should work, but still does not display. Similar to the condition directive. Am still f..king around with it.

[lsmarsden]

Changelog

v1.6.0

• Added ability to invert progress using invert: true.

[lsmarsden]

Changelog

v1.7.0

• Added ability to define multiple configurations for the same button.
  Define separate configuration blocks with conditions, and the configuration matching the condition will be used.
  If multiple configurations match, the first one in the list will be used.

Example - Two configurations for main button to show different sources on different conditions:

icon_border_progress:
  - button: main
    source: vacuum.robo_vac[battery_level]
    condition:
      condition: "state",
      entity_id: "vacuum.robo_vac",
      state: "docked",
    color_stops:
      - percent: 0
        color: "red"
      - percent: 100
        color: "green"
  - button: main
    source: vacuum.robo_vac[cleaning_progress]
    condition:
      condition: "state",
      entity_id: "vacuum.robo_vac",
      state: "cleaning",
    color_stops:
      - percent: 0
        color: "blue"

[ddkedr]

Hey, mate! Thank you for your job! It's great.

Is it possible to make a progress bar disappear when the value reaches "0" ?

Now it still shows a dot like it's 1 percent remaining

Now I'm hacking this with color stops by making the 0% color transparent

    color_stops:
      "0":
        color: "#5c53660"
        percent: 0
      "1":
        color: "#5c5366"
        percent: 1

But this does not seem optimal

[CykloneFij]

Mate, just read the 1.7.0 release notes above your post!
Use conditions, numeric_state maybe

[ddkedr]

As I've mentioned in my post, I am using conditions for percentage points.

But you didn't get my point. I'm saying this is a bug. A progress bar at 0% shouldn't look like it's 1%. It should be fully empty

[lsmarsden]

Hi, I had noticed this bug before, but I thought I solved it... Did you upgrade to v1.7.0?

When I use sensors that give a value of 0 it seems to work fine. Could you provide the state values of your sensors that are showing this problem just to make sure they are not showing very small decimal values? The current module behaviour should always set the stroke colour to transparent automatically when the progress value is 0:

  if (progressValue <= 0) {
    // Make progress invisible when 0 or less - keeps transitions working
    progressPath.setAttribute("stroke", "transparent");
    progressPath.setAttribute("stroke-dasharray", `0 ${pathLength}`);
    progressPath.setAttribute("stroke-dashoffset", "0");
  }

[julien94800]

Hi @lsmarsden
I use your module and I like it!!
But since several times it looks like below for sub button even with standard settings (on iOS app)
Do you have any idea about how to revert back to round shape? I tried playing with settings but without success

[lsmarsden]

Looking closer at your screenshot it looks like the styling is conflicting with something. The icon border ring is there as normal but it looks like it's extra-thick and an overflow is hiding the rest of it. Have you applied any global stylings or used any other global modules that apply to all cards recently? I just downloaded Bubble Card 3.0.3 and it still looks ok, so there are no issues with that version either.

[julien94800]

Good point, but no global module applied, and in my test I even created the card on a fresh new dashboard by activating only this card. So I assume no global customisation applied there. I might be missing something, but I can't get any idea from where it comes from.
FYI, I'm on latest version of HA and bubble card too.
I don't know if I can clean all modules history or something like that to be sure I get everything stored fine. I tried looking in manually installed modules but nothing linked to your module

[julien94800]

Hello again,
I just deleted the whole module, and installed it back. It's working great now. So strange...
I will see if it happens again in next days.
Thanks anyway!!!
Really awesome module

[julien94800]

Last issue I still have is the following one... circle seems to be not well cantered

(especially visible in dark mode, we can see some small white portions near circle)

[julien94800]

Sorry for spam... but I might have found the root cause of this small thing.
It only happens when I add a bubble separator before my bubble icon card.
Bubble separator has default height of 0.8
If I switch separator height from 0.8 to 1 (manually), then circles seems to become coincident again.
Do you reproduce this behaviour??

[GeorgeCastanza]

Thanks. Just discovered this, and love it. Appreciate all your hard work.