# Layout Patterns

URL: /chirp/docs/build-apps/html-fragments/layout-patterns/
Section: html-fragments
Tags: templates, blocks, layout, composition

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

Overview Chirp templates use Kida's block system: &#123;% extends %&#125;, &#123;% block %&#125;, &#123;% include %&#125;, and &#123;% call %&#125;. This guide covers patterns for using each construct and composing pages inside a shell. Pick a shell first. Your templates &#123;% extends %&#125; one of three root layouts (boost.html, shell.html, or chirp-ui's app_shell_layout.html). See Shells for the decision table and the hx-select distinction. This guide assumes a shell is already chosen. For fixed column ratios on page content (grid() + block(span=…)), see the Chirp UI package docs/LAYOUT-OVERFLOW.md (section Fixed columns: grid presets). Extending a Shell Whatever shell you picked, the extension shape is the same: &#123;% extends &quot;chirp/layouts/boost.html&quot; %&#125; {# or shell.html, or chirpui/app_shell_layout.html #} &#123;% block title %&#125;My App&#123;% end %&#125; &#123;% block content %&#125; &lt;p&gt;Page content goes here.&lt;/p&gt; &#123;% end %&#125; &#123;% block body_after %&#125; &lt;script&gt;/* app-specific JS */&lt;/script&gt; &#123;% end %&#125; The core shells expose the same block names — title, head, body_before, content, sse_scope, body_after — so migrating between them is a one-line change. chirp-ui's app_shell_layout.html adds shell-specific blocks (brand, sidebar, page_root, page_content); see App Shells. Important: Put sse_scope outside #main. If it's inside content, it gets replaced on navigation and live updates stop. Outer vs Inner Content For SSE swap targets and fragment structure: Outer element — The sse-swap target. Holds padding, border, layout. Stays in the DOM; its innerHTML is replaced. Inner element — The fragment block content. No duplicate padding or border. &lt;!-- Outer: swap target, has padding/border; hx-target=&quot;this&quot; when sse-connect has hx-disinherit --&gt; &lt;div class=&quot;answer&quot; sse-swap=&quot;answer&quot; hx-target=&quot;this&quot;&gt; &lt;!-- Inner: fragment renders this; no extra padding --&gt; &lt;div class=&quot;answer-body&quot; data-copy-text=&quot;...&quot;&gt; &lt;div class=&quot;answer-content prose&quot;&gt;...&lt;/div&gt; &lt;button class=&quot;copy-btn&quot;&gt;Copy&lt;/button&gt; &lt;/div&gt; &lt;/div&gt; Avoid nesting two elements with the same padding/border — it causes double spacing. Keep .copy-btn in normal flow (no position: absolute) so it stays with its answer. When to Use Each Construct Construct Use for &#123;% extends %&#125; Base layout (boost, custom shell). One per template. &#123;% block %&#125; Overridable sections. Child templates fill or extend. &#123;% include %&#125; Reusable partials (headers, footers, cards). No block params. &#123;% call %&#125; Macros with parameters. Use with &#123;% def %&#125;. Blocks define slots; includes pull in full partials; call/def are parameterized components. Block Inheritance Child templates override blocks by redefining them: &#123;% extends &quot;base.html&quot; %&#125; &#123;% block content %&#125; {{ super() }} &lt;p&gt;Additional content after parent block.&lt;/p&gt; &#123;% end %&#125; &#123;&#123; super() &#125;&#125; renders the parent block's content. Omit it to replace entirely. Next Steps Shells — Pick the right root layout (boost, shell, app-shell) and the hx-select distinction Fragments — Block-level rendering for htmx App Shells — Persistent sidebar layout with SPA navigation RAG Demo — Full layout example with SSE and shell.html

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

Metadata:
- Word Count: 446
- Reading Time: 2 minutes