{"id":13515837,"url":"https://github.com/github/include-fragment-element","last_synced_at":"2025-05-14T00:08:13.028Z","repository":{"id":21346308,"uuid":"24663344","full_name":"github/include-fragment-element","owner":"github","description":"A client-side includes tag.","archived":false,"fork":false,"pushed_at":"2025-04-14T15:39:51.000Z","size":2220,"stargazers_count":552,"open_issues_count":2,"forks_count":41,"subscribers_count":325,"default_branch":"main","last_synced_at":"2025-05-10T04:10:03.137Z","etag":null,"topics":["custom-elements","web-components"],"latest_commit_sha":null,"homepage":"https://github.github.io/include-fragment-element/examples","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-01T02:35:47.000Z","updated_at":"2025-04-14T15:39:55.000Z","dependencies_parsed_at":"2025-04-10T02:17:56.400Z","dependency_job_id":"41835771-0908-4473-846e-c0c972ea9ad9","html_url":"https://github.com/github/include-fragment-element","commit_stats":{"total_commits":323,"total_committers":20,"mean_commits":16.15,"dds":0.7678018575851393,"last_synced_commit":"5249243ee1cbdc82ab69c5d7c6318cd61a524b93"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Finclude-fragment-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Finclude-fragment-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Finclude-fragment-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Finclude-fragment-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/include-fragment-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043969,"owners_count":22005042,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-elements","web-components"],"created_at":"2024-08-01T05:01:16.475Z","updated_at":"2025-05-14T00:08:12.979Z","avatar_url":"https://github.com/github.png","language":"JavaScript","readme":"# \u0026lt;include-fragment\u0026gt; element\n\nA Client Side Includes tag.\n\n## Installation\n\n```\n$ npm install --save @github/include-fragment-element\n```\n\n## Usage\n\nAll `include-fragment` elements must have a `src` attribute from which to retrieve an HTML element fragment.\n\nThe initial page load should include fallback content to be displayed if the resource could not be fetched immediately.\n\n```js\nimport '@github/include-fragment-element'\n```\n\n**Original**\n\n``` html\n\u003cdiv class=\"tip\"\u003e\n  \u003cinclude-fragment src=\"/tips\"\u003e\n    \u003cp\u003eLoading tip…\u003c/p\u003e\n  \u003c/include-fragment\u003e\n\u003c/div\u003e\n```\n\nOn page load, the `include-fragment` element fetches the URL, the response is parsed into an HTML element, which replaces the `include-fragment` element entirely.\n\n**Result**\n\n``` html\n\u003cdiv class=\"tip\"\u003e\n  \u003cp\u003eYou look nice today\u003c/p\u003e\n\u003c/div\u003e\n```\n\nThe server must respond with an HTML fragment to replace the `include-fragment` element. It should not contain _another_ `include-fragment` element or the server will be polled in an infinite loop.\n\n### Other Attributes\n\n#### accept\n\nThis attribute tells `\u003cinclude-fragment/\u003e` what to send as the `Accept` header, as part of the fetch request. If omitted, or if set to an empty value, the default behaviour will be `text/html`. It is important that the server responds with HTML, but you may wish to change the accept header to help negotiate the right content with the server.\n\n#### loading\n\nThis indicates _when_ the contents should be fetched:\n\n - `eager`: Fetches and load the content immediately, regardless of whether or not the `\u003cinclude-fragment/\u003e` is currently within the visible viewport (this is the default value).\n - `lazy`: Defers fetching and loading the content until the `\u003cinclude-fragment/\u003e` tag reaches a calculated distance from the viewport. The intent is to avoid the network and storage bandwidth needed to handle the content until it's reasonably certain that it will be needed.\n\n### Errors\n\nIf the URL fails to load, the `include-fragment` element is left in the page and tagged with an `is-error` CSS class that can be used for styling.\n\n### Events\n\nRequest lifecycle events are dispatched on the `\u003cinclude-fragment\u003e` element.\n\n- `loadstart` - The server fetch has started.\n- `load` - The request completed successfully.\n- `error` - The request failed.\n- `loadend` - The request has completed.\n- `include-fragment-replace` (cancelable) - The success response has been parsed. It comes with `event.detail.fragment` that will replace the current element.\n- `include-fragment-replaced` - The element has been replaced by the fragment.\n\n```js\nconst loader = document.querySelector('include-fragment')\nconst container = loader.parentElement\nloader.addEventListener('loadstart', () =\u003e container.classList.add('is-loading'))\nloader.addEventListener('loadend', () =\u003e container.classList.remove('is-loading'))\nloader.addEventListener('load', () =\u003e container.classList.add('is-success'))\nloader.addEventListener('error', () =\u003e container.classList.add('is-error'))\n```\n\n### Options\n\nAttribute      | Options                        | Description\n---            | ---                            | ---\n`src`          | URL string                     | Required URL from which to load the replacement HTML element fragment.\n\n\n### Deferred loading\n\nThe request for replacement markup from the server starts when the `src` attribute becomes available on the `\u003cinclude-fragment\u003e` element. Most often this will happen at page load when the element is rendered. However, if we omit the `src` attribute until some later time, we can defer loading the content at all.\n\nThe [`\u003cdetails-menu\u003e`][menu] element uses this technique to defer loading menu content until the menu is first opened.\n\n[menu]: https://github.com/github/details-menu-element\n\n## Patterns\n\nDeferring the display of markup is typically done in the following usage patterns.\n\n- A user action begins a slow running background job on the server, like backing up files stored on the server. While the backup job is running, a progress bar is shown to the user. When it's complete, the include-fragment element is replaced with a link to the backup files.\n\n- The first time a user visits a page that contains a time-consuming piece of markup to generate, a loading indicator is displayed. When the markup is finished building on the server, it's stored in memcache and sent to the browser to replace the include-fragment loader. Subsequent visits to the page render the cached markup directly, without going through a include-fragment element.\n\n### CSP Trusted Types\n\nYou can call `setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise\u003cTrustedTypePolicy\u003e | null)` from JavaScript to set a [CSP trusted types policy](https://web.dev/trusted-types/), which can perform (synchronous) filtering or rejection of the `fetch` response before it is inserted into the page:\n\n```ts\nimport IncludeFragmentElement from \"include-fragment-element\";\nimport DOMPurify from \"dompurify\"; // Using https://github.com/cure53/DOMPurify\n\n// This policy removes all HTML markup except links.\nconst policy = trustedTypes.createPolicy(\"links-only\", {\n  createHTML: (htmlText: string) =\u003e {\n    return DOMPurify.sanitize(htmlText, {\n      ALLOWED_TAGS: [\"a\"],\n      ALLOWED_ATTR: [\"href\"],\n      RETURN_TRUSTED_TYPE: true,\n    });\n  },\n});\nIncludeFragmentElement.setCSPTrustedTypesPolicy(policy);\n```\n\nThe policy has access to the `fetch` response object. Due to platform constraints, only synchronous information from the response (in addition to the HTML text body) can be used in the policy:\n\n```ts\nimport IncludeFragmentElement from \"include-fragment-element\";\n\nconst policy = trustedTypes.createPolicy(\"require-server-header\", {\n  createHTML: (htmlText: string, response: Response) =\u003e {\n    if (response.headers.get(\"X-Server-Sanitized\") !== \"sanitized=true\") {\n      // Note: this will reject the contents, but the error may be caught before it shows in the JS console.\n      throw new Error(\"Rejecting HTML that was not marked by the server as sanitized.\");\n    }\n    return htmlText;\n  },\n});\nIncludeFragmentElement.setCSPTrustedTypesPolicy(policy);\n```\n\nNote that:\n\n- Only a single policy can be set, shared by all `IncludeFragmentElement` fetches.\n- You should call `setCSPTrustedTypesPolicy()` ahead of any other load of `include-fragment-element` in your code.\n  - If your policy itself requires asynchronous work to construct, you can also pass a `Promise\u003cTrustedTypePolicy\u003e`.\n  - Pass `null` to remove the policy.\n- Not all browsers [support the trusted types API in JavaScript](https://caniuse.com/mdn-api_trustedtypes). You may want to use the [recommended tinyfill](https://github.com/w3c/trusted-types#tinyfill) to construct a policy without causing issues in other browsers.\n\n## Relation to Server Side Includes\n\nThis declarative approach is very similar to [SSI](http://en.wikipedia.org/wiki/Server_Side_Includes) or [ESI](http://en.wikipedia.org/wiki/Edge_Side_Includes) directives. In fact, an edge implementation could replace the markup before its actually delivered to the client.\n\n``` html\n\u003cinclude-fragment src=\"/github/include-fragment/commit-count\" timeout=\"100\"\u003e\n  \u003cp\u003eCounting commits…\u003c/p\u003e\n\u003c/include-fragment\u003e\n```\n\nA proxy may attempt to fetch and replace the fragment if the request finishes before the timeout. Otherwise the tag is delivered to the client. This library only implements the client side aspect.\n\n## Browser support\n\nBrowsers without native [custom element support][support] require a [polyfill][]. Legacy browsers require various other polyfills. See [`examples/index.html`][example] for details.\n\n[example]: https://github.com/github/include-fragment-element/blob/master/examples/index.html#L5-L14\n\n- Chrome\n- Firefox\n- Safari\n- Microsoft Edge\n\n[support]: https://caniuse.com/#feat=custom-elementsv1\n[polyfill]: https://github.com/webcomponents/custom-elements\n\n## Development\n\n```\nnpm install\nnpm test\n```\n\n## License\n\nDistributed under the MIT license. See LICENSE for details.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Finclude-fragment-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Finclude-fragment-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Finclude-fragment-element/lists"}