Skip to content
Kona

Includes & partials

Partials are ordinary views meant to be composed into other templates — navigation, flash banners, form field snippets. Crema does not use a separate “fragment” file type: any view name can be included. Includes share the parent’s sections and stacks through a child data context (parent keys remain visible; the include can read the same name, user, and so on).

Always include

Section titled “Always include”
@include('partials.nav')

Resolves src/main/resources/views/partials/nav.crema.html (dotted name → path). Missing views throw ViewNotFoundException.

{{-- views/partials/nav.crema.html --}}
<nav>
  <a href="/">Home</a>
  @auth
    <a href="/account">Account</a>
  @endauth
</nav>

Optional include

Section titled “Optional include”
@includeIf('optional.banner')

Renders nothing when the view file is missing (no error). Use this for theme overrides or optional packages.

Conditional include

Section titled “Conditional include”
@includeWhen(showBanner, 'partials.banner')
@includeUnless(hideBanner, 'partials.banner')
Directive Renders the view when…
@includeWhen(expr, 'name') expr is truthy
@includeUnless(expr, 'name') expr is not truthy

First available view

Section titled “First available view”
@includeFirst(['theme.banner', 'partials.banner'])

Renders the first quoted name that resolves; skips missing views without error. If none resolve, emits nothing.

Useful for “prefer theme, fall back to default” partials:

@includeFirst([
  'themes.current.flash',
  'partials.flash',
])

@once

Section titled “@once”
@once
  <script>window.__konaFlash = true;</script>
@endonce

The body renders at most once per render pass, even if the partial that contains it is included many times. Identical @once bodies share the same key. Stacks and sections still work inside the body on the first pass.

@verbatim

Section titled “@verbatim”
@verbatim
  Document {{ this }} and @if(examples) literally.
@endverbatim

Nothing inside @verbatim…@endverbatim is processed as Crema — echoes and directives are left as text. Use this in documentation pages or when embedding template examples inside a Crema layout.

Partials vs layouts vs components

Section titled “Partials vs layouts vs components”
Approach When to use
@include Small shared chunks (nav, field, alert strip)
@extends / @section Full page shells with named regions — Layouts
@component / <x-*> Reusable widgets with a default slot and optional named slots — Components

Includes do not isolate stacks: a @push('scripts') inside a partial still lands on the layout’s @stack('scripts').

Next

Section titled “Next”