Include

Fetches an external HTML file and embeds its contents inline on the page. Useful for reusing shared markup like headers, footers, and partials across multiple pages.

<cs-include src="/assets/examples/include.html"></cs-include>

Included files are asynchronously requested using window.fetch(). Requests are cached, so the same file can be included multiple times, but only one request will be made.

The included content will be inserted into the <cs-include> element’s default slot so it can be easily accessed and styled through the light DOM.

Examples

Including Part of a File

To include just one section of a file instead of the whole thing, add the target element’s id as a hash to the src. Only the matching element’s content is included, the rest of the file is ignored.

If the file loads but the id isn’t found, the cs-include-error event is emitted.

<cs-include src="/assets/examples/include.html#callout-fragment"></cs-include>

Including a Template

The same #id syntax also works against the current page, which is handy for reusing markup you’ve defined once. It pairs especially well with a <template>, whose content stays hidden until it’s included.

You get what’s inside the target, not the target element itself, either the children of a regular element, or the contents of a <template>. The original stays in place, so you can include it any number of times.

<template id="greeting">
  <cs-callout variant="brand">
    <cs-icon slot="icon" name="waving_hand"></cs-icon>
    Hello from a template!
  </cs-callout>
</template>

<cs-include src="#greeting"></cs-include>

Listening for Events

When an include file loads successfully, the cs-load event will be emitted. You can listen for this event to add custom loading logic to your includes.

If the request fails, the cs-include-error event will be emitted. In this case, event.detail.status will contain the resulting HTTP status code of the request, e.g. 404 (not found).

<cs-include src="/assets/examples/include.html"></cs-include>

<script>
  const include = document.querySelector('cs-include');

  include.addEventListener('cs-load', event => {
    if (event.eventPhase === Event.AT_TARGET) {
      console.log('Success');
    }
  });

  include.addEventListener('cs-include-error', event => {
    if (event.eventPhase === Event.AT_TARGET) {
      console.log('Error', event.detail.status);
    }
  });
</script>

API

Importing

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick this component, use one of the following snippets.

import '@cruglobal/cornerstone-components/components/include/include.js';

import './cornerstone/components/include/include.js';

import CsInclude from '@cruglobal/cornerstone-components/react/include/index.js';

Attributes & Properties

Learn more about attributes and properties.

Events

Learn more about events.

SSR

Learn more about Server-Side Rendering (SSR).

<cs-include> fetches its content asynchronously (like <cs-icon>), so the rendered output isn't available during SSR.