Since Shoelace 2.0 Code stable

Include

sl-include

Includes give you the power to embed external HTML files into the page.

Examples

Include Basics

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 <sl-include> element’s default slot so it can be easily accessed and styled through the light DOM. 

<sl-include src="https://shoelace.style/assets/examples/include.html"></sl-include>

sl-include src="https://shoelace.style/assets/examples/include.html"

Listening for Events

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

If the request fails, the sl-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). 

<sl-include src="https://shoelace.style/assets/examples/include.html"></sl-include>

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

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

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

Component Props

Property Default Details
src —

string

The location of the HTML file to include. Be sure you trust the content you are including as it will be executed as code and can result in XSS attacks.

mode 'cors'

'cors' | 'no-cors' | 'same-origin'

The fetch mode to use.
allowScripts
allow-scripts 		false

boolean

Allows included scripts to be executed. Be sure you trust the content you are including as it will be executed as code and can result in XSS attacks.

updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name Name Name React Event Details
sl-load sl-load sl-load onSlLoad

Emitted when the included file is loaded.
sl-error sl-error sl-error onSlError

{ status: number }

Emitted when the included file fails to load due to an error.

Learn more about events.