# Provide / Consume

URL: /docs/usage/provide-consume/
Section: usage
Tags: usage, components, context

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

Provide / Consume &#123;% provide %&#125; and consume() let a parent push state that any descendant can read -- across slot boundaries, includes, and imported macros -- without passing it through every layer of parameters. Quick start &#123;% provide theme = &quot;dark&quot; %&#125; {{ consume(&quot;theme&quot;) }} {# &quot;dark&quot; #} &#123;% endprovide %&#125; provide pushes a value onto a per-key stack. consume reads the top of that stack, or returns a default if the key is absent. Syntax provide &#123;% provide key = expr %&#125; ...body... &#123;% endprovide %&#125; key -- a plain name (not a string). expr -- any expression: a literal, variable, function call, etc. The body can contain any template content. &#123;% end %&#125; is accepted as a shorthand for &#123;% endprovide %&#125;. consume {{ consume(&quot;key&quot;) }} {{ consume(&quot;key&quot;, default) }} key -- a string naming the provided value. default -- returned when no provider for that key is active. Defaults to None when omitted. Nesting and shadowing Providers nest. An inner provide with the same key shadows the outer one for the duration of its body, then the outer value is automatically restored: &#123;% provide color = &quot;red&quot; %&#125; {{ consume(&quot;color&quot;) }} {# &quot;red&quot; #} &#123;% provide color = &quot;blue&quot; %&#125; {{ consume(&quot;color&quot;) }} {# &quot;blue&quot; #} &#123;% end %&#125; {{ consume(&quot;color&quot;) }} {# &quot;red&quot; again #} &#123;% end %&#125; Independent keys coexist without interference: &#123;% provide a = 1 %&#125; &#123;% provide b = 2 %&#125; {{ consume(&quot;a&quot;) }}, {{ consume(&quot;b&quot;) }} {# 1, 2 #} &#123;% end %&#125; &#123;% end %&#125; Components: table + row The motivating use case is implicit configuration between paired components. A table provides alignment metadata that row consumes, so callers never pass alignment to every row by hand: {# components/table.html #} &#123;% def table(headers, align=none) %&#125; &#123;% provide _table_align = align %&#125; &lt;table&gt; &lt;thead&gt; &lt;tr&gt;&#123;% for h in headers %&#125;&lt;th&gt;{{ h }}&lt;/th&gt;&#123;% end %&#125;&lt;/tr&gt; &lt;/thead&gt; &lt;tbody&gt;&#123;% slot %&#125;&lt;/tbody&gt; &lt;/table&gt; &#123;% endprovide %&#125; &#123;% end %&#125; &#123;% def row(*cells) %&#125; &#123;% set align = consume(&quot;_table_align&quot;) %&#125; &lt;tr&gt; &#123;% for cell in cells %&#125; &lt;td&#123;% if align %&#125; class=&quot;align-{{ align[loop.index0] }}&quot;&#123;% endif %&#125;&gt; {{ cell }} &lt;/td&gt; &#123;% end %&#125; &lt;/tr&gt; &#123;% end %&#125; Usage: &#123;% from &quot;components/table.html&quot; import table, row %&#125; &#123;% call table(headers=[&quot;Name&quot;, &quot;Count&quot;], align=[&quot;left&quot;, &quot;right&quot;]) %&#125; {{ row(&quot;Alice&quot;, &quot;42&quot;) }} {{ row(&quot;Bob&quot;, &quot;17&quot;) }} &#123;% end %&#125; row never receives alignment as a parameter -- it reads it from the nearest table ancestor via consume. Theme provider pattern Another common pattern: a theme wrapper that sets context for all descendant components. &#123;% def theme_provider(name=&quot;light&quot;) %&#125; &#123;% provide theme = name %&#125; &lt;div class=&quot;theme-{{ name }}&quot;&gt;&#123;% slot %&#125;&lt;/div&gt; &#123;% endprovide %&#125; &#123;% end %&#125; &#123;% def button(label) %&#125; &lt;button class=&quot;btn btn-{{ consume(&quot;theme&quot;, &quot;light&quot;) }}&quot;&gt;{{ label }}&lt;/button&gt; &#123;% end %&#125; Nested providers override the theme for their subtree: &#123;% call theme_provider(&quot;dark&quot;) %&#125; {{ button(&quot;Save&quot;) }} {# btn-dark #} &#123;% call theme_provider(&quot;accent&quot;) %&#125; {{ button(&quot;Upgrade&quot;) }} {# btn-accent #} &#123;% end %&#125; {{ button(&quot;Cancel&quot;) }} {# btn-dark (restored) #} &#123;% end %&#125; Where consume works Provided values are visible everywhere the render context is shared: Boundary Visible? Slot content (&#123;% call %&#125;...&#123;% end %&#125;) Yes Macro calls (&#123;&#123; child() &#125;&#125;) Yes Imported macros (&#123;% from &quot;x.html&quot; import y %&#125;) Yes Includes (&#123;% include &quot;x.html&quot; %&#125;) Yes Child templates (inheritance) Yes Error safety provide compiles to a try/finally block, so the stack is always cleaned up -- even when the body raises an exception. After an error, a fresh render starts with a clean provider state. Naming conventions Use an underscore prefix for keys that are internal to a component pair: &#123;% provide _table_align = align %&#125; {# internal to table/row #} Use plain names for user-facing configuration: &#123;% provide theme = &quot;dark&quot; %&#125; Example A full working example is in examples/provide_consume/.

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

Metadata:
- Word Count: 629
- Reading Time: 3 minutes