# Jinja2 vs Kida: Components

URL: /docs/tutorials/component-comparison/
Section: tutorials
Tags: tutorial, components, jinja2, migration

--------------------------------------------------------------------------------

Jinja2 vs Kida: Components A real-world dashboard card component built in both engines. Same HTML output, very different authoring experience. The component has: Typed props (title, subtitle, variant) A header actions slot A default body slot An optional footer Co-located CSS Theming via context (not prop drilling) The Jinja2 Version Component Definition {# components/card.html (Jinja2) #} {# No type annotations — params are a guessing game #} &#123;% macro card(title, subtitle=&quot;&quot;, variant=&quot;default&quot;) %&#125; &lt;article class=&quot;card card--{{ variant }}&quot;&gt; &lt;header class=&quot;card__header&quot;&gt; &lt;div&gt; &lt;h3&gt;{{ title }}&lt;/h3&gt; &#123;% if subtitle %&#125;&lt;p class=&quot;card__subtitle&quot;&gt;{{ subtitle }}&lt;/p&gt;&#123;% endif %&#125; &lt;/div&gt; {# No named slots — caller() is all-or-nothing #} &lt;/header&gt; &lt;div class=&quot;card__body&quot;&gt; {{ caller() }} &lt;/div&gt; &lt;/article&gt; &#123;% endmacro %&#125; Problems: No type annotations on parameters caller() gives you one blob of content — no way to target header actions vs body vs footer separately No has_slot() — can't conditionally render a footer wrapper Usage {# pages/dashboard.html (Jinja2) #} &#123;% from &quot;components/card.html&quot; import card %&#125; {# Need to pass theme through every layer #} &#123;% call card(&quot;Settings&quot;, subtitle=&quot;Manage preferences&quot;, variant=&quot;elevated&quot;) %&#125; &lt;form&gt; &lt;label&gt;Theme&lt;/label&gt; {# How do we read the current theme? It must be passed as a variable #} &lt;select name=&quot;theme&quot;&gt; &lt;option &#123;% if theme == &quot;light&quot; %&#125;selected&#123;% endif %&#125;&gt;Light&lt;/option&gt; &lt;option &#123;% if theme == &quot;dark&quot; %&#125;selected&#123;% endif %&#125;&gt;Dark&lt;/option&gt; &lt;/select&gt; &lt;/form&gt; &#123;% endcall %&#125; Scoping Trap Jinja2's &#123;% set %&#125; leaks out of blocks. This causes subtle bugs: {# Jinja2 — count leaks across iterations #} &#123;% set count = 0 %&#125; &#123;% for section in sections %&#125; &#123;% set count = count + 1 %&#125; {# count is now modified in the OUTER scope #} &#123;% endfor %&#125; {# count == len(sections), not 0 — the set leaked #} To work around this, Jinja2 requires the namespace() pattern: {# Jinja2 — namespace workaround #} &#123;% set ns = namespace(count=0) %&#125; &#123;% for section in sections %&#125; &#123;% set ns.count = ns.count + 1 %&#125; &#123;% endfor %&#125; {{ ns.count }} Co-located Styles Jinja2 has no content stacks. You must manage CSS separately: {# base.html (Jinja2) #} &lt;head&gt; &lt;link rel=&quot;stylesheet&quot; href=&quot;/css/main.css&quot;&gt; {# No way for components to inject styles here #} &#123;% block extra_styles %&#125;&#123;% endblock %&#125; &lt;/head&gt; {# Every page that uses card must manually add its CSS #} &#123;% block extra_styles %&#125; &lt;link rel=&quot;stylesheet&quot; href=&quot;/css/card.css&quot;&gt; &#123;% endblock %&#125; Styles are disconnected from the component that needs them. Context / Theming Jinja2 has no provide/consume. To theme nested components, you must pass the value through every layer: {# Jinja2 — prop drilling #} &#123;% macro page_shell(theme) %&#125; {{ sidebar(theme=theme) }} &lt;main&gt;{{ caller() }}&lt;/main&gt; &#123;% endmacro %&#125; &#123;% macro sidebar(theme) %&#125; &lt;nav class=&quot;sidebar sidebar--{{ theme }}&quot;&gt; {{ sidebar_item(&quot;Home&quot;, &quot;/&quot;, theme=theme) }} {{ sidebar_item(&quot;Settings&quot;, &quot;/settings&quot;, theme=theme) }} &lt;/nav&gt; &#123;% endmacro %&#125; &#123;% macro sidebar_item(label, url, theme) %&#125; &lt;a class=&quot;sidebar__item sidebar__item--{{ theme }}&quot; href=&quot;{{ url }}&quot;&gt; {{ label }} &lt;/a&gt; &#123;% endmacro %&#125; Three layers deep, and every one must forward theme. Error Handling Jinja2 has no error boundaries. One broken component crashes the entire page: {# Jinja2 — if user.profile is None, the whole page 500s #} &#123;% call card(user.profile.display_name) %&#125; {{ render_activity(user.id) }} &#123;% endcall %&#125; The Kida Version Component Definition {# components/card.html (Kida) #} &#123;% def card(title: str, subtitle: str | None = none, variant: str = &quot;default&quot;) %&#125; &#123;% push &quot;styles&quot; %&#125; &lt;style&gt; .card { border: 1px solid var(--border); border-radius: 8px; overflow: hidden; } .card--elevated { box-shadow: 0 2px 8px rgba(0,0,0,0.1); } .card__header { padding: 16px; display: flex; justify-content: space-between; } .card__body { padding: 0 16px 16px; } .card__footer { padding: 12px 16px; border-top: 1px solid var(--border); } &lt;/style&gt; &#123;% end %&#125; &lt;article class=&quot;card card--{{ variant }}&quot;&gt; &lt;header class=&quot;card__header&quot;&gt; &lt;div&gt; &lt;h3&gt;{{ title }}&lt;/h3&gt; &#123;% if subtitle %&#125;&lt;p class=&quot;card__subtitle&quot;&gt;{{ subtitle }}&lt;/p&gt;&#123;% end %&#125; &lt;/div&gt; &#123;% slot header_actions %&#125; &lt;/header&gt; &lt;div class=&quot;card__body&quot;&gt; &#123;% slot %&#125; &lt;/div&gt; &#123;% if has_slot(&quot;footer&quot;) %&#125; &lt;footer class=&quot;card__footer&quot;&gt; &#123;% slot footer %&#125; &lt;/footer&gt; &#123;% end %&#125; &lt;/article&gt; &#123;% end %&#125; What's different: Feature Jinja2 Kida Type annotations No title: str, subtitle: str | None Named slots No (caller() only) &#123;% slot header_actions %&#125;, &#123;% slot footer %&#125; Conditional slot wrapper No has_slot(&quot;footer&quot;) Co-located styles No &#123;% push &quot;styles&quot; %&#125; Validated at check time No kida check --validate-calls Usage {# pages/dashboard.html (Kida) #} &#123;% from &quot;components/card.html&quot; import card %&#125; &#123;% provide theme = &quot;dark&quot; %&#125; &#123;% call card(&quot;Settings&quot;, subtitle=&quot;Manage preferences&quot;, variant=&quot;elevated&quot;) %&#125; &#123;% slot header_actions %&#125; &lt;button class=&quot;btn btn--icon&quot; aria-label=&quot;Save&quot;&gt;Save&lt;/button&gt; &#123;% end %&#125; &lt;form&gt; &lt;label&gt;Theme&lt;/label&gt; &lt;select name=&quot;theme&quot;&gt; &lt;option &#123;% if consume(&quot;theme&quot;) == &quot;light&quot; %&#125;selected&#123;% end %&#125;&gt;Light&lt;/option&gt; &lt;option &#123;% if consume(&quot;theme&quot;) == &quot;dark&quot; %&#125;selected&#123;% end %&#125;&gt;Dark&lt;/option&gt; &lt;/select&gt; &lt;/form&gt; &#123;% slot footer %&#125; &lt;button type=&quot;submit&quot;&gt;Apply&lt;/button&gt; &#123;% end %&#125; &#123;% end %&#125; &#123;% end %&#125; Header actions, body, and footer are separate slots — targeted, not jumbled Theme comes from consume(&quot;theme&quot;), not a prop passed through every layer Styles are co-located in the component and rendered in &lt;head&gt; via &#123;% stack &quot;styles&quot; %&#125; Scoping Kida's &#123;% set %&#125; is block-scoped. No leaking, no namespace() workaround: {# Kida — set is block-scoped, use let for template-wide #} &#123;% let count = 0 %&#125; &#123;% for section in sections %&#125; &#123;% set count = count + 1 %&#125; {# This count is local to the for loop — outer count is still 0 #} &#123;% end %&#125; {# count == 0 — no leaking #} {# To modify outer scope, use export #} &#123;% let total = 0 %&#125; &#123;% for section in sections %&#125; &#123;% export total = total + 1 %&#125; &#123;% end %&#125; {# total == len(sections) — explicit, intentional #} Context / Theming No prop drilling. Set the theme once, read it anywhere: &#123;% def page_shell() %&#125; {{ sidebar_nav() }} &lt;main&gt;&#123;% slot %&#125;&lt;/main&gt; &#123;% end %&#125; &#123;% def sidebar_nav() %&#125; &lt;nav class=&quot;sidebar sidebar--{{ consume(&#x27;theme&#x27;) }}&quot;&gt; {{ sidebar_item(&quot;Home&quot;, &quot;/&quot;) }} {{ sidebar_item(&quot;Settings&quot;, &quot;/settings&quot;) }} &lt;/nav&gt; &#123;% end %&#125; &#123;% def sidebar_item(label: str, url: str) %&#125; &lt;a class=&quot;sidebar__item sidebar__item--{{ consume(&#x27;theme&#x27;) }}&quot; href=&quot;{{ url }}&quot;&gt; {{ label }} &lt;/a&gt; &#123;% end %&#125; Zero mentions of theme in any function signature. Each component reads what it needs from context. Error Boundaries Wrap risky components so failures degrade gracefully: &#123;% try %&#125; &#123;% call card(user.profile.display_name) %&#125; {{ render_activity(user.id) }} &#123;% end %&#125; &#123;% fallback error %&#125; &lt;div class=&quot;card card--error&quot; role=&quot;alert&quot;&gt; &lt;p&gt;Could not load this card.&lt;/p&gt; &lt;/div&gt; &#123;% end %&#125; The rest of the page renders normally even if this card fails. Static Validation $ kida check templates/ --validate-calls templates/pages/dashboard.html:8: Call to &#x27;card&#x27; — unknown params: titl templates/pages/settings.html:14: type: badge() param &#x27;count&#x27; expects int, got str (&quot;five&quot;) Jinja2 has no equivalent — parameter errors surface at runtime. Summary Capability Jinja2 Kida Type annotations on params No param: str | None Compile-time call validation No kida check --validate-calls Named slots No &#123;% slot name %&#125; Conditional slot rendering No has_slot(&quot;name&quot;) Scoped slot data (data up) No let:item=expr Block-scoped variables No (set leaks) &#123;% set %&#125; is block-scoped Explicit outer-scope mutation namespace() hack &#123;% export %&#125; Context propagation Prop drilling only &#123;% provide %&#125; / consume() Error boundaries No &#123;% try %&#125;...&#123;% fallback %&#125; Co-located component styles No &#123;% push %&#125; / &#123;% stack %&#125; Component discovery CLI No kida components Component introspection API No template.def_metadata() Pattern matching if/elif chains &#123;% match %&#125; / &#123;% case %&#125; Content stacks No &#123;% push %&#125; / &#123;% stack %&#125; Both engines produce the same HTML. The difference is in how you get there — and what happens when things go wrong. See Also Components Guide — Full patterns reference Coming from Jinja2 — Quick cheat sheet Migration Guide — Step-by-step migration Feature Comparison — Full feature matrix

--------------------------------------------------------------------------------

Metadata:
- Word Count: 1253
- Reading Time: 6 minutes