include-file

Load remote HTML fragments with progressive enhancement. Fallback content shows until fetch completes.

Overview

The <include-file> component fetches HTML from a URL and injects it. Any existing content serves as a fallback shown until the fetch completes (or if it fails).

<include-file src="/partials/header.html"> <p>Loading header...</p> </include-file>

Attributes

Attribute Type Default Description
src URL — URL to fetch HTML from.
data-mode string replace How to insert content: replace, append, or prepend.
data-lazy boolean — Defer loading until the element enters the viewport.
data-loading boolean — Auto-set while fetching. Can be styled with VB loading utilities.
data-loaded boolean — Auto-set after successful load.
data-error boolean — Auto-set if fetch fails.

Lazy Loading

Add data-lazy to defer the fetch until the element scrolls into view (with a 200px root margin).

<!-- Only loads when scrolled into view --> <include-file src="/partials/comments.html" data-lazy> <p>Comments loading...</p> </include-file>

Insert Modes

Control how the fetched HTML is inserted with data-mode.

<!-- Replace (default) --> <include-file src="/partials/content.html" data-mode="replace"></include-file> <!-- Append to existing content --> <include-file src="/partials/more.html" data-mode="append"> <p>Existing content stays.</p> </include-file> <!-- Prepend before existing content --> <include-file src="/partials/banner.html" data-mode="prepend"> <p>This moves down.</p> </include-file>

Events

Event Detail Description
include-file:load { src, html } Fired after successful load.
include-file:error { src, error } Fired if the fetch fails.
const include = document.querySelector('include-file'); include.addEventListener('include-file:load', (e) => { console.log('Loaded:', e.detail.src); }); include.addEventListener('include-file:error', (e) => { console.error('Failed:', e.detail.error); });

JavaScript API

Method Description
reload() Re-fetch content from the current src.

Progressive Enhancement

Without JavaScript, the fallback content (whatever HTML is inside the element) remains visible. The src URL is never fetched, so users see the fallback. This makes it safe to use for non-critical content.

Accessibility

  • Fallback content ensures content is always available.
  • Error state shows a message when content fails to load (unless fallback content exists).
  • Changing the src attribute triggers a re-fetch, enabling dynamic content updates.

Related Elements

  • <iframe> — Embeds an entire document (heavier, sandboxed)