Feature request for Jinja templating

[iAmRenzo]

I discovered your Bubble Card, I really love it but my dashboard is now filled with Jinja templating. It's an extreme fuss to convert it into conditional JS.
Also Jinja is used throughout Home Assistant.

[Airblader]

@Clooos Do you have thoughts on this? I find myself doing a lot of things that Jinja would make much easier that JS often just cannot do (well). Disclaimer, I have no idea what is involved in supporting templates. 🙂

[Impudicus]

Would love to see this

[emteedubs]

I'm already familiar with jinja templating from using home assistant, it makes it harder to customize bubble cards as now I have to learn a new language. Also makes converting my mushroom cards much harder since I have to figure out how to translate those jinja templates into conditional js

[Impudicus]

Not only it is harder, homeassistant was made to define a standard for everyone. Make different labels compatible, so "one can rule them all". This shall include, that developers agree on using home assistants jinja templating

[nagtegaal]

If HA was made to define one standard for everyone, this would be part of the API itself imo. And would not be against all contrib integrations to implement it or not.
To me, it doesn't seem that this is going to be part of the core API.

[nagtegaal]

Is there any progress on this at all? Or is this never considered a feature at all to be implemented?

[Impudicus]

This thread is dead as hell — no responses at all

[Clooos]

Hi! This is still in my to-do list but this will needs a lot of works, I'm currently working to have a strong basis with the full pop-up refactoring.

Working on this project is taking a lot of time and I can't progress on everything at the same time, but this will come! 😄

[psychuk]

I would also love to see this, especially in modules, the ability to inject module variables into the yaml or the styling would be epic!

[nagtegaal]

Native Jinja2 templates in the styles: field (mixable with JavaScript)

Please be careful while testing and do not use inside a production environment. Patch is against latest bubble-card v3.3.0 beta 3.

Summary

@Clooos This patch adds native Home Assistant Jinja2 support to the styles: field, which is used by virtually every Bubble Card. Jinja2 ({{ ... }} and {% ... %}) and the existing JavaScript templates (${ ... }) can be mixed freely in the same value — nothing about the current JavaScript behaviour changes.

It is deliberately scoped to the styles: field only, as a first step, because that field already imports the template-change reactivity hook and is shared across all card types.

Applies cleanly on top of v3.3.0-beta.3. Touches only two files under src/tools/; the built dist/ bundle is intentionally not included (rebuild with npm run dist).

Motivation

Bubble Card already ships a complete Jinja2 rendering engine in src/tools/render-template.js (getRenderedTemplate), and it is already wired into validate-condition.js (Jinja conditions) and style-processor.js (style reactivity). Until now, however, {{ }} could only influence styles indirectly, via checkConditionsMet called from inside a ${ } expression. Many users keep their dashboards in Jinja and have repeatedly asked to use it directly (see discussions #1944 and #1260). This change lets them paste their existing Jinja straight into styles:.

How it works

The styles: value has always been compiled as a JavaScript template literal (return `<styles>`), which is what evaluates ${ ... }. This patch resolves the Jinja2 parts to concrete text before that compilation step:

1. A styles value is split into JavaScript ${ ... } spans and literal spans. ${ ... } spans are left completely untouched and still execute exactly as before.
2. Each literal span that contains Jinja is sent to Home Assistant as a whole through the existing getRenderedTemplate subscription, so block tags such as {% if %} ... {% endif %} are evaluated together. Single CSS braces ({, }) are literal text to Jinja and pass through unchanged.
3. The rendered result is spliced back in, and the combined string is compiled and executed as today.

Reactivity is already provided by the existing onTemplateChange subscription in handleCustomStyles: when a template result changes, getRenderedTemplate notifies subscribers, the card re-renders, and the memoization fingerprint (which already includes _templateResultVersion) is invalidated. While a server result is still pending, the span renders to an empty string and is filled in on the follow-up render.

Example

type: custom:bubble-card
card_type: button
entity: light.kitchen
styles: |
  .bubble-icon-container {
    /* JavaScript template — unchanged */
    background: ${state === 'on' ? 'orange' : 'grey'};
  }
  {% if is_state('sensor.mode', 'night') %}
  .bubble-name { opacity: 0.5; }
  {% endif %}
  .bubble-sub-button {
    /* Jinja expression inline */
    border-color: {{ state_attr('light.kitchen', 'rgb_color') | join(',') }};
  }

Safety

Rendered Jinja output is treated as data, not source. Before it is embedded in the JavaScript template literal, the three sequences that are special there — `, ${, and \ — are escaped, so a backtick or ${...} coming from, say, a sensor's state value cannot break compilation or inject JavaScript. Pure JavaScript ${ } spans keep their existing template-literal semantics.

Correctness details

• _isStaticTemplate() now also treats the presence of {{ }} / {% %} as non-static, so a Jinja-only style (no ${) is never frozen in the global static cache and correctly re-evaluates when its server-rendered result changes.
• Jinja detection is memoized per template string, consistent with the other per-template caches in the file.
• The compiled-function cache is keyed on the resolved (post-Jinja) source, so a changed Jinja result recompiles correctly.

Scope / limitations

• Intentionally limited to the styles: field. Text fields such as name and state are not covered here and can follow in a separate change.
• Within a Jinja-containing literal span, output is inserted verbatim (backslashes are literal). Pure JavaScript ${ } spans are unaffected and keep the existing escape handling.
• The ${ } scanner skips over string and template literals when brace-matching; deeply nested template literals inside a single ${ } expression are an untested edge case, but this mirrors what users already write today.

Tests

Six unit tests added to src/tools/style-processor.test.js:

• resolves a {{ }} expression through Home Assistant;
• mixes JavaScript ${ } and Jinja {{ }} in one value;
• renders a {% if %} ... {% endif %} block as a single template;
• renders empty while the server result is pending;
• escapes rendered output so it cannot break out of the JS literal (injection guard);
• leaves a JavaScript-only template untouched and never calls the server (no regression).

Full suite: 946 tests pass, and npm run dist (webpack) builds successfully.

Files changed

• src/tools/style-processor.js — Jinja detection, ${ }/literal span splitter, server rendering + escaping, static-cache and compile-cache adjustments.
• src/tools/style-processor.test.js — mock update and the six tests above.

bubble-card-jinja-styles.patch

[nagtegaal]

Native Jinja2 in the name and sub-button name fields

Please be careful while testing and do not use inside a production environment. Patch is against latest bubble-card v3.3.0 beta 3.

Summary

@Clooos Follow-up to the styles-field Jinja2 change. This patch lets the card name (name, including button_type: name) and sub-button names contain native Home Assistant Jinja2 ({{ ... }} / {% ... %}). Plain strings behave exactly as before. It reuses the existing render_template subscription engine, and broadens the existing template-change handler so these text fields update reactively (not just styles).

Stacked PR. This change builds on top of the styles-field Jinja2 patch (“Native Jinja2 templates in the styles: field”). Apply that one first. The two production changes are independent, but this patch’s test additions share context with the first patch’s test file.

Applies on top of v3.3.0-beta.3 + the styles patch. Full suite: 953 tests pass; npm run dist builds successfully.

Motivation

Templating the name field is one of the most requested Bubble Card features (see discussion #1260, “Allow using templates in the name field”, and #1944). The engine to do it — getRenderedTemplate in src/tools/render-template.js, already used for conditions and styles — has been in place for a while; this simply routes the relevant text fields through it.

What is covered

• Card name — config.name for every card that renders a name (button, cover, separator, pop-up header, climate, …), via getName(), plus the button_type: name path that reads config.name directly.
• Sub-button name — the name shown by a sub-button, via buildDisplayedState().

Deliberately not covered

The state / attribute lines are derived from the entity itself (hass.formatEntityState / formatEntityAttributeValue), not from a user-authored string, so there is nothing to “template” there in the same way. To show a computed value on the state line, write into .bubble-state from the styles field, which the companion patch already makes Jinja-capable. Keeping the state path untouched also avoids changing entity-state formatting for everyone.

How it works

A small shared helper is added to src/tools/utils.js:

export function resolveTemplateText(context, value) {
  if (typeof value !== "string" || value === "") return value;
  if (!TEXT_JINJA_TEMPLATE_RE.test(value)) return value; // plain string → untouched
  const hass = context?._hass;
  if (!hass || !hass.connection) return "";
  const rendered = getRenderedTemplate(hass, value, { entity: context?.config?.entity });
  return rendered === undefined ? "" : String(rendered);
}

• A value with no {{ }} / {% %} is returned unchanged — zero behaviour change and no server round-trip for plain names.
• A Jinja value is rendered server-side through the existing subscription. While the first result is still pending it renders to an empty string (rather than leaking raw braces), and the card re-renders once the value arrives.
• getName() and the button_type: name branch in base-card/changes.js route config.name through the helper; buildDisplayedState() routes the sub-button name through it. Text is written via innerText / scrolling textContent, so no HTML injection is possible.

Reactivity

A template result arrives asynchronously over the websocket, often after the hass update that caused it. The card already keeps a single onTemplateChange subscription (created in handleCustomStyles, stored on the card, cleaned up in disconnectedCallback), but its handler only refreshed styles. This patch broadens that handler to re-render the whole card when the card exposes an update entry point:

if (typeof context.updateBubbleCard === 'function') {
  context.updateBubbleCard();          // refreshes name + sub-buttons + styles
} else {
  handleCustomStyles(context, targetElement); // fallback: direct STYLE element / detached preview
}

No new subscription and no new teardown path — it reuses the one that already exists. There is no re-render loop: a re-render reads the now-cached template result, which does not fire another change.

Example

type: custom:bubble-card
card_type: button
entity: climate.living
name: "{{ state_attr('climate.living','current_temperature') }}°"
sub_button:
  - entity: sensor.humidity
    name: "{{ 'Wet' if states('sensor.humidity')|float > 60 else 'Dry' }}"

Tests

Added to src/tools/utils.test.js:

• plain string returned untouched, server never called;
• a {{ }} value rendered through Home Assistant;
• empty string while the result is pending;
• no raw braces before hass is ready;
• getName() renders a Jinja name; a plain name is left alone.

Added to src/tools/style-processor.test.js:

• a template-result change re-renders the whole card (so name / sub-button name update), not just the styles.

Full suite: 953 tests pass; webpack build succeeds.

Files changed

• src/tools/utils.js — resolveTemplateText() helper + getName() routing.
• src/components/base-card/changes.js — route the button_type: name path through the helper.
• src/components/sub-button/utils.js — route the sub-button name through the helper.
• src/tools/style-processor.js — broaden the template-change handler to re-render text fields.
• *.test.js — mock updates and the tests above.
  bubble-card-jinja-text-fields.patch

[Clooos]

Hi! In fact this was in my plans for v3.3.0 but that version was getting a bit too big and I decided to leave this for the next one, but I will check your patch and see if this can be added in the next beta 👌

A PR would have been a more standard approach but thank you for this!

[nagtegaal]

I know, you already told me that on Reddit where I asked about the Jinja2 templating support. ;-)

Perhaps, if 3.3.0 beta 3 is stable and complete now: release it as it is.
Then apply the patch to HEAD and make it an 4.0 alpha release, which could be tested and build further up.

Or release it all together... The JS template is still there, so there shouldn't be a problem when upgrading for the end users.

[nagtegaal]

So, how is this working out for you? Is it an option to implement it in bubble-card?

[Clooos]

I will release v3.3.0 first then I will check that once it is fully stable, as you said this is probably the safest path 🙂

[Clooos]

Hi! I haven't used your code because there was too many changes to make, but Jinja templates will be available in v3.4.0 (for names, icons, sub-buttons and styles) 🍻

[Clooos]

Hi! Jinja templates will finally be available in v3.4.0! You will be able to use these to customize names, icons, sub-buttons and styles 🍻

[nagtegaal]

Great! Looking forward to it! Any (b)ETA yet?

[Clooos]

I will not release this version in beta for once, this one is stable enough (I've made A LOT of tests) and will be available in a few days 😄