Skip to main content
Includes let you embed one template inside another. Use them for reusable partials like navigation bars, footers, and sidebars.

​
Basic include

Use #include to embed a partial. The argument is a dot-notation template name that resolves to a .lex file in your configured view paths. 
#include('partials.header')
This embeds partials/header.lex at the point of the directive.

​
Passing extra data

Pass an associative array as a second argument to inject additional variables into the included template’s scope. 
#include('partials.nav', ['active' => 'home'])
Inside partials/nav.lex, $active is available as a local variable.

​
#includeIf

Use #includeIf to include a partial only when the template file exists. No error is thrown if the file is missing. 
#includeIf('partials.sidebar')
This is useful for optional template regions that may not be present in all project configurations.

​
#includeWhen

Use #includeWhen to conditionally include a partial based on a PHP expression. The partial is only loaded when the condition is truthy. 
#includeWhen($user->isAdmin(), 'partials.admin-bar')
You can also pass extra data as a third argument: 
#includeWhen($user->isAdmin(), 'partials.admin-bar', ['user' => $user])

​
#includeFirst

Use #includeFirst to include the first template that exists from a list. This is useful for theme overrides — define a preferred path first and fall back to a default. 
#includeFirst(['theme.header', 'partials.header'])
Lex checks each name in order and includes the first file it finds. If none of the files exist, no output is produced.

​
Scope isolation

Included templates render in an isolated scope. Sections defined inside an included partial do not leak into the parent layout’s #yield slots. Each included template is a self-contained rendering unit. 
<!-- partials/widget.lex -->
#section('extra')
    This section does NOT appear in the parent layout's #yield('extra').
#endsection

<div class="widget">{{ $title }}</div>
If you need to push content into a parent layout’s stacks, use #push / #endpush inside the included partial instead — stack accumulation works across include boundaries.

​
Dynamic includes and the dependency graph

Lex builds a dependency graph to automatically invalidate compiled templates when a partial they depend on changes. This graph is populated at compile time by reading the static string arguments of include directives.
Dynamic include expressions — where the template name is a variable rather than a string literal — are not tracked in the dependency graph. If you change a partial that is only referenced dynamically, templates that include it will not be automatically recompiled.
<!-- Tracked: Lex knows this template depends on partials/header.lex -->
#include('partials.header')

<!-- Not tracked: Lex cannot resolve the name at compile time -->
#include($partialName)
For dynamically included partials you should clear the compiled cache manually after making changes, or use static includes wherever possible.

Build docs developers (and LLMs) love

Get started for freeTalk to us