Documentation

Everything you need to keep words together.

Install the package, pick your framework, and put brackets around the phrases that should never break. This page is the README, so it always matches the published package.

View .mdEdit on GitHub

Install

npm install wordhug

Each framework is an optional peer dependency; install only the one you use.

Framework Import from Peer dependency Text goes in
React wordhug/react react 18+ children
Vue wordhug/vue vue 3.3+ default slot
Solid wordhug/solid solid-js and @solidjs/web 2+ children
Svelte wordhug/svelte svelte 5+ text prop
Astro wordhug/astro – text prop
None wordhug – wordhugHtml
Markdown wordhug/rehype – markdown text

Upgrading from 0.1

The React component moved to its own subpath. Change the import:

- import { WordHug } from "wordhug";
+ import { WordHug } from "wordhug/react";

parseBrackets is still imported from wordhug.

Usage

React

import { WordHug } from "wordhug/react";

export function Hero() {
  return (
    <h1>
      <WordHug>{"Fresh bread [delivered daily] to [your door]"}</WordHug>
    </h1>
  );
}

WordHug has no hooks and no "use client" directive, so it renders in React Server Components as well as on the client.

Prop Type Default Description
children React.ReactNode – Text and elements to render (see below). Empty input renders nothing.
as React.ElementType "span" Element that wraps each group.
className string – Class name on each group wrapper.
style CSSProperties | null { display: "inline-block" } Inline style on each group wrapper. Pass null to style groups only through className.

Strings and numbers in the children are joined into one text, including inside arrays and fragments, so JSX expressions work inside brackets. Elements stay where they are, and a group can contain them: each element is one unit that is never split. Brackets inside an element are not read, so a group can't start in one element and end in another.

<WordHug>Hello [{user.name}], you have [{count} new messages]</WordHug>
<WordHug>Fresh bread for [only <strong>$3</strong> a loaf]</WordHug>

wordhug()

The same thing as a function that returns a React node, for places where a component is awkward, such as props that take a node or text built in a loop. It takes the same input as children and the same options as the props.

import { wordhug } from "wordhug/react";

<Button label={wordhug("Save [all changes]")} />;
wordhug("Pay [only $9.99]", { className: "nowrap", style: null });

Vue

<script setup>
import { WordHug } from "wordhug/vue";
</script>

<template>
  <h1><WordHug class="nowrap">Fresh bread [delivered daily] to [your door]</WordHug></h1>
</template>

The text comes from the default slot: plain text and {{ }} interpolations are joined into one text, and elements and components stay where they are, each as one unit a group can contain. Brackets inside an element are not read. class and style go on each group wrapper, not on a root element. style defaults to display: inline-block; :style="null" removes it. as takes a tag name or a component and defaults to "span".

wordhug(text, options) returns the same output as a VNode, for render functions, Vue JSX or anything that expects a VNode. Options are as, class and style, as for the component:

import { h } from "vue";
import { wordhug } from "wordhug/vue";

h("h1", [wordhug("Fresh bread [delivered daily]", { class: "nowrap" })]);

Solid

import { WordHug } from "wordhug/solid";

<h1>
  <WordHug class="nowrap">{"Fresh bread [delivered daily] to [your door]"}</WordHug>
</h1>;

Props: children (string), as (tag or component, default "span"), class, and style (object or string, default { display: "inline-block" }, null removes it). Re-renders when any prop changes. Requires Solid 2.

wordhug(text, options) returns the same output as a JSX.Element, for props that take an element or text built in a loop. It reads its arguments once, so call it inside JSX ({wordhug(title())}) or a memo to keep it reactive:

import { wordhug } from "wordhug/solid";

<Button label={wordhug("Save [all changes]", { class: "nowrap" })} />;

Svelte

<script>
  import { WordHug } from "wordhug/svelte";
</script>

<h1><WordHug text="Fresh bread [delivered daily] to [your door]" /></h1>

Props: text (string), as (tag name, default "span"), class, and style (string, default "display: inline-block", null removes it). Requires Svelte 5; the component ships as source and is compiled by your build.

Astro

---
import WordHug from "wordhug/astro";
---

<h1><WordHug text="Fresh bread [delivered daily] to [your door]" /></h1>

Same props as Svelte: text, as, class, style. Renders static HTML with no client JavaScript.

Plain HTML: wordhugHtml

import { wordhugHtml } from "wordhug";

wordhugHtml("Fish & [chips]", { class: "nowrap" });
// → 'Fish &amp; <span class="nowrap" style="display: inline-block">chips</span>'

Options are as (tag name), class and style, as for Svelte. Text and attributes are HTML-escaped, so the result is safe to insert with innerHTML.

This was called renderToHtml before 0.3. The old name still works but is deprecated and will be removed in a future release.

Markdown: wordhug/rehype

A rehype plugin, for markdown and anything else that goes through unified, such as Astro's markdown, MDX and many CMS pipelines. Writers put brackets in their markdown and groups come out in the HTML.

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeWordhug from "wordhug/rehype";

const html = String(
  await unified()
    .use(remarkParse)
    .use(remarkRehype)
    .use(rehypeWordhug, { class: "nowrap" })
    .use(rehypeStringify)
    .process("Fresh bread [delivered daily] to [your door]"),
);

In Astro, add it to markdown.rehypePlugins in astro.config.mjs:

import rehypeWordhug from "wordhug/rehype";

export default { markdown: { rehypePlugins: [rehypeWordhug] } };

Options are as (tag name), class and style, as for wordhugHtml.

The plugin runs after markdown is parsed, so links ([text](url)), references with a definition, footnotes and task list boxes are already handled; only brackets left in the text become groups. A group can contain inline formatting such as **bold** or *italic*, but can't start in one element and end in another. Code spans, code blocks and <pre>, <script> and <style> are left alone, and text without groups is left exactly as it was.

Markdown removes a backslash before a bracket, so for a literal bracket write two backslashes: \\[sic\\] renders [sic].

Styling

Groups work without any stylesheet: each wrapper gets display: inline-block inline. To use a class instead (for example Tailwind's inline-block or whitespace-nowrap), pass a class and a null style.

An inline-block group moves to the next line as a whole. If a group is wider than its container, it still wraps inside its own box rather than overflowing. Use white-space: nowrap if you would rather it never break and overflow instead. Note that a parent's text-decoration (such as a link underline) does not carry into inline-block groups.

Parsing rules

  • [...] marks a group. Groups can nest: [a [b c] d].
  • A bracket without a partner is kept as literal text: a ] b and a [ b render unchanged.
  • Runs of whitespace collapse to a single space, and whitespace at the start and end of the text and of each group is removed.
  • Text touching a bracket stays attached: (see [page 3]) renders (see <span>page 3</span>).
  • Empty groups ([]) are dropped.
  • To show a literal bracket, put a backslash before it: \[sic\] renders [sic] and never forms a group. A backslash before any other character is kept as is.

In JSX text, Vue and Svelte templates and Astro attributes a backslash is literal, so <WordHug>Quote \[sic\]</WordHug> and text="Quote \[sic\]" work as written. Inside a JavaScript string the backslash itself needs escaping: {"Quote \\[sic\\]"}.

parseBrackets

The parser is exported from the package root, which imports no framework, so you can render the tree any way you like.

import { parseBrackets } from "wordhug";

parseBrackets("Hello [big world] today");
// [
//   { type: "text", value: "Hello " },
//   { type: "group", children: [{ type: "text", value: "big world" }] },
//   { type: "text", value: " today" },
// ]

Types Node, TextNode, GroupNode and WordhugHtmlOptions are exported from wordhug, and RehypeWordhugOptions from wordhug/rehype; WordHugProps is exported from wordhug/react, wordhug/solid and wordhug/svelte, and WordHugOptions from wordhug/react, wordhug/vue and wordhug/solid.