v0.1.0

Orphan Obliterator

Prevent orphaned words on the last line of HTML elements. Scoped via CSS selectors, configurable with font‑size thresholds, word‑count minimums, and more.

bunx github:doublej/orphan-obliterator

Before

Good typography prevents
words from ending up all
alone.

After

Good typography prevents
words from ending
up all alone.

Features

CSS Selector Scoping

Target any elements with standard CSS selectors. Apply different rules to paragraphs, headings, and list items independently.

Font-Size Thresholds

Skip elements above or below a font-size threshold. Keep large headings untouched while fixing body text orphans.

Word Count Minimum

Only apply to elements with enough words. Short phrases are left alone — no awkward forced joins on two-word lines.

Multi-Line Detection

Optionally skip single-line elements entirely. Only fix orphans where text actually wraps to multiple lines.

Live Observers

Watch for DOM mutations and window resizes. Content loaded dynamically or reflowed responsively stays orphan-free.

Clean Teardown

Call destroy() to restore all original text and disconnect observers. No side effects left behind.

Getting Started

Install

Add the package to your project.

bun add orphan-obliterator

Import and call

Pass a CSS selector string for the simplest usage.

import { obliterate } from 'orphan-obliterator'

const instance = obliterate('p, li, h2')

Configure rules

Fine-tune with word count, font-size, and line detection rules.

const instance = obliterate({
  selectors: ['p', '.content li'],
  rules: {
    minWords: 4,
    maxFontSize: '24px',
    minLastLineWords: 2,
  },
  observe: true,
  responsive: true,
})

Rules Reference

Rule	Type	Default	Description
`minWords`	`number`	`4`	Skip elements with fewer words
`maxFontSize`	`string`	`—`	Skip if font-size exceeds this (e.g. '24px', '1.5rem')
`minFontSize`	`string`	`—`	Skip if font-size is below this
`minLastLineWords`	`number`	`2`	Words to keep together at end
`maxProtectedChars`	`number`	`25`	Skip if joined group exceeds this length
`onlyMultiLine`	`boolean`	`false`	Only apply to multi-line elements

API

`obliterate(input): OrphanInstance`

Accepts a CSS selector string, a config object, or an array of config objects. Processes matching elements immediately and returns an instance.

instance.update()

Re-process all matching elements.

instance.destroy()

Restore original text and disconnect all observers.