Light SST Light Dark SST Dark System

Include

<sl-include> | SlInclude
Since 2.0 stable

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

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.

The content in this example was included from a separate file. đŸ¤¯

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Lectus vestibulum mattis ullamcorper velit sed ullamcorper morbi. Fringilla urna porttitor rhoncus dolor purus non enim. Nullam vehicula ipsum a arcu cursus vitae congue mauris. Gravida in fermentum et sollicitudin.

Cursus sit amet dictum sit amet justo donec enim. Sed id semper risus in hendrerit gravida. Viverra accumsan in nisl nisi scelerisque eu ultrices vitae. Et molestie ac feugiat sed lectus vestibulum mattis ullamcorper velit. Nec ullamcorper sit amet risus nullam. Et egestas quis ipsum suspendisse ultrices gravida dictum. Lorem donec massa sapien faucibus et molestie. A cras semper auctor neque vitae. 

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

import SlInclude from '@shoelace-style/shoelace/dist/react/include';

const App = () => <SlInclude src="https://shoelace.style/assets/examples/include.html" />;

Examples

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>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

Properties

Name Description Reflects Type Default
src 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. string -
mode The fetch mode to use. 'cors' | 'no-cors' | 'same-origin' 'cors'
allowScripts
allow-scripts 		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. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
sl-load onSlLoad Emitted when the included file is loaded. -
sl-error onSlError Emitted when the included file fails to load due to an error. { status: number }

Learn more about events.