Skip to content
@staticbolt/core

HTML Insert Plugin

A plugin for staticbolt that adds a custom <insert> tag. At build time it injects HTML content into any element on the page, picked with a CSS selector.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install another package.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { htmlInsertPlugin } from "@staticbolt/core/plugins";


export default defineConfig({
  plugins: [htmlInsertPlugin()],
});

The <insert> tag

The <insert> tag lets you inject content into any element on the page by targeting it with a CSS selector. The children of the tag go into the target, and the <insert> tag itself is removed from the output.

This helps in layouts and partials. A component can add a <link> or <script> to the <head> without having direct access to it.

<insert selector="head">
  <link rel="stylesheet" href="./component.css" />
</insert>

Attributes

selector (required)

A CSS selector for the target element that receives the content.

<insert selector="head">
  <meta name="description" content="My page" />
</insert>

where

Controls where the content is inserted relative to the target element. Accepts any valid insertAdjacentHTML position. Defaults to "beforeend".

Value Inserts
beforebegin Before the target element itself
afterbegin Inside the target, before its first child
beforeend Inside the target, after its last child (default)
afterend After the target element itself 
<insert selector="body" where="afterbegin">
  <div class="banner">Site is in maintenance mode</div>
</insert>

replace

A boolean attribute. When it is present, the inserted content replaces the target element entirely instead of going inside it.

<insert selector="#placeholder" replace>
  <section class="hero">...</section>
</insert>

Plugin Options

tagName

  • Type: string
  • Default: "insert"

The tag name of the custom insert element.

htmlInsertPlugin({
  tagName: "teleport",
});

selectorAttribute

  • Type: string
  • Default: "selector"

The attribute name that holds the CSS selector of the target element.

htmlInsertPlugin({
  selectorAttribute: "target",
});

whereAttribute

  • Type: string
  • Default: "where"

The attribute name that holds the insertion position.

htmlInsertPlugin({
  whereAttribute: "position",
});

replaceAttribute

  • Type: string
  • Default: "replace"

The attribute name that makes the plugin replace the target element instead of inserting into it.

htmlInsertPlugin({
  replaceAttribute: "swap",
});