rehype plugin to replace slot elements in an HTML fragment.

Replacement value is provided as a HAST tree

This package is ESM only.

Install the rehype-slots npm module:

npm install rehype-slots

import rehypeSlots from "rehype-slots";

Take this HTML fragment which contains <slot> elements:

<h1>
  <slot name="title"></slot>
</h1>
<article>
  <div>
    <slot name="quote"></slot>
  </div>
  <div>
    <slot name="author">Anonymous</slot>
  </div>
</article>

Provide the slot values to be inserted, in this case using hastscript to create the HAST tree:

import { h } from "hastscript";

const values = {
  // a string that will create a text node
  title: "A Tale Of Two Cities",

  // a HAST tree that will be inserted
  quote: h("p", "It was the best of times..."),
};

In the following code, rehype-slots will traverse the HTML tree and replace each <slot> element with the value that was provided for it, based on the name attribute.

If a <slot> element is encountered but no value was provided for it, then the element's contents will be used as a default value.

import { unified } from "unified";
import rehypeParse from "rehype-parse";
import rehypeFormat from "rehype-format";
import rehypeStringify from "rehype-stringify";
import rehypeSlots from "rehype-slots";

unified()
  .use(rehypeParse, { fragment: true })
  .use(rehypeSlots, { values }) // <-- attach the rehype-slots plugin
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process(input)
  .then((output) => {
    console.log(output.contents);
  });

Output:

<h1>A Tale Of Two Cities</h1>
<article>
  <div>
    <p>It was the best of times...</p>
  </div>
  <div>Anonymous</div>
</article>

Notice in the output:

• the title slot was replaced with a string
• the quote slot was replaced with an HTML tree (HAST)
• no value was provided for the author slot, so the slot element's contents were used as the default value.

Replace slot elements with the provided values.

Object containing slot names and slot values. (object, default: {})

Allowed value types:

• String (will be converted to a HAST text node)
• HAST node
• HAST root (document, fragment or template)
• Array of HAST nodes
• Function that returns any of the above. The function will be called with the slot name as the first argument.

Defines the behavior when a slot is not found in the values object. It can be one of the following:

• "unwrap": Replace the slot with its own children, i.e. unwrap it. This is the default.
• "remove": Remove the slot element entirely.
• "keep": Do nothing, keep the slot element as it is.

A function that will be called for each slot whose name was not found in the values object. It will be called with (slotName, slotElement) and can return a value to replace the slot with, or return undefined to use the fallback behavior.

Tag name of the element to replace, if you want to use a different element than slot which is the default.

Name of the attribute on the slot element that holds the slot's name. The default is name.

Submit an issue if you find a bug or want to request a feature. Pull requests are welcome.

See Developing for more information on how to develop this project.

MIT © Marek Zaluski