Include

The include directive makes it easy to fetch and insert an external HTML fragment inside an element. The request is restricted to the same domain, protocol and port as the application.

Usage

Use x-h-include to compose a page from smaller same-origin HTML fragments, for example reusable headers, footers, or partial views loaded on demand. Point it at a relative path to the fragment. By default any script in the fragment is ignored, so set data-js only when you trust the source and need its scripts to run.

WARNING

• Only use on trusted content and never on dynamic/user-provided content!
  
• Dynamically rendering HTML from third parties can easily lead to XSS vulnerabilities.
  
• Executing untrusted JavaScript code poses significant security risks and should be strictly avoided.

INFO

The directive executes before any binding.

API Reference

Component attribute(s)

x-h-include

Arguments

Attribute	Type	Required	Description
self	string	true	Relative path to the HTML fragment.

Attributes

Attribute	Type	Required	Description
data-js	boolean	false	By default, the directive does not execute any JavaScript code. If the fragment includes a script that should execute, set this to true.

Modifiers

Modifier	Description
js	Replaced by data-js

Events

Event	Bubbles	Detail	Description
fragment:loaded	No	{ url }	Dispatched on the element after the fragment is inserted into the DOM and Alpine has initialized the new tree.
fragment:error	No	{ url, status, error }	Dispatched on the element when the response has a non-200 HTTP status code, when the script inside the fragment fails to execute or when the script link inisde the fragment does not resolve. status is can be undefined for the last two cases.

Examples

<div x-h-include="'/harmonia/components/include/fragment.html'"></div>

Reacting after load

Because fragment:loaded does not bubble, attach the listener directly to the element:

<div x-h-include="'/harmonia/components/include/fragment.html'" @fragment:loaded="onFragmentLoaded($event.detail.url)"></div>

Or in plain JavaScript:

const el = document.querySelector('#my-include');
el.addEventListener('fragment:loaded', (e) => {
  console.log('Loaded:', e.detail.url);
});

Handling a failed load

fragment:error does not bubble either, so attach the listener directly to the element. $event.detail.status holds the HTTP status code, or undefined when the request itself failed:

<div x-h-include="'/harmonia/components/include/missing.html'" @fragment:error="onFragmentError($event.detail.url, $event.detail.status)"></div>

Or in plain JavaScript:

const el = document.querySelector('#my-include');
el.addEventListener('fragment:error', (e) => {
  console.log('Failed:', e.detail.url, e.detail.status);
});