Include
<quiet-include>
Fetches HTML from a URL and injects it into the page at runtime. Use an include to pull in shared headers, footers, navigation, and other partials without a build step or server-side templating.
<quiet-include src="/assets/examples/include.html"></quiet-include>
Examples Jump to heading
Default content Jump to heading
You can provide default content inside the include, which will be shown until the request completes. This is useful to show a loading state while the include file is fetched.
<quiet-include src="/assets/examples/include.html">
Loading content…
</quiet-include>
Including fragments Jump to heading
To include just part of a file, append a fragment to the URL, e.g. page.html#some-id. The
content of the first element with a matching id in the fetched file will be included. If no
matching element is found, the quiet-include-error event will be emitted.
<quiet-include src="/assets/examples/include-fragment.html#calico"></quiet-include>
You can also include content from elsewhere in the current document by using a fragment by itself, e.g.
#some-id. Same-document includes don't make an HTTP request, making them a lightweight way to
reuse repetitive content.
This content was included from a hidden element in the same document. No cats were fetched in the making of this example.
<quiet-include src="#include__same-document"></quiet-include>
<div hidden>
<div id="include__same-document">
<p>This content was included from a hidden element in the same document. No cats were fetched in the making of this example.</p>
</div>
</div>
Allowing scripts Jump to heading
Scripts included in the fetched HTML will not be executed by default. If you trust the content, you can use
the allow-scripts attribute to allow them to run.
<quiet-include allow-scripts src="/assets/examples/include-scripts.html"></quiet-include>
Using this option can be dangerous! Make sure you trust the included content, otherwise your app may become vulnerable to XSS exploits!
Handling events Jump to heading
When an include file is successfully rendered, the quiet-included event will be emitted. When
things go wrong, the quiet-include-error event will be emitted instead. This happens when a
network error occurs, when the response has an HTTP status outside of the 200 range, or when a requested
fragment can't be found.
You can inspect event.detail.error to see the associated error. If an HTTP status code was
returned, it will be available in event.detail.status.
<quiet-include src="/assets/examples/include.html" id="include__events"></quiet-include>
<script>
const include = document.getElementById('include__events');
include.addEventListener('quiet-included', () => {
//
// The include file has rendered
//
});
include.addEventListener('quiet-include-error', event => {
//
// Something went wrong. You can inspect event.detail.error
// to see the error and, if an HTTP status code was returned,
// event.detail.status to see which code was provided.
//
});
</script>
API Jump to heading
Importing Jump to heading
The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.
To manually import <quiet-include> from the CDN, use the following code.
import 'https://cdn.quietui.org/v5.3.1/components/include/include.js';
To manually import <quiet-include> from a self-hosted distribution, use the following
code. Remember to replace /path/to/quiet with the appropriate local path.
import '/path/to/quiet/components/include/include.js';Properties Jump to heading
Include has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties
| Property | Description | Reflects | Type | Default |
|---|---|---|---|---|
src
|
The URL of the file to include. Must be a CORS-enabled endpoint. To include only part of a file,
append a fragment such as page.html#some-id and the content of the first element with a
matching id will be included. To include content from the current document, use a
fragment by itself, e.g. #some-id.
|
|
string
|
|
mode
|
The mode to use when fetching the request. |
|
RequestMode
|
'cors'
|
allowScripts
allow-scripts
|
By default, scripts in included files will not be executed. Setting this to true will allow them to run. If you use this option, make sure you trust the included HTML, otherwise you may become vulnerable to XSS exploits. |
|
boolean
|
false
|
Events Jump to heading
Include dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events
| Name | Description |
|---|---|
quiet-included |
Emitted when the include file has been fetched and rendered. The HTTP status code will be available
in event.detail.status, except for same-document includes, which don't make an HTTP
request. This event does not bubble.
|
quiet-include-error |
Emitted when the fetch results in a network error, receives an HTTP response outside of the 200
range, or when a requested fragment can't be found. If a network error occurs, it will be available
in event.detail.error. If an HTTP status code was returned, it will be available in
event.detail.status. This event does not bubble.
|