prevent-widows

In typography, a widow is a short word or line at the end of a paragraph that appears alone on the last line, which can negatively impact readability and visual appearance.

This module replaces the spaces and hyphens at the end of a paragraph with non-breaking spaces and non-breaking hyphens to prevent widows.

It comes with support for strings and posthtml (optional).

Installation

npm install prevent-widows
# - or -
yarn add prevent-widows

Usage

Basic String Processing

import preventWidows from "prevent-widows";
const text = "The quick brown fox jumped over the lazy dog";
const result = preventWidows(text);
// "The quick brown fox jumped over the lazy dog"

Options

encoding

Defines the type of output to transform the spaces and hyphens.

• Since: 1.0.0
• Property is Optional
• Default value is: Encodings.HTML
• Validation rules:
  • Must be a type of Encoding

This table describes how values will be transformed depending on what type of pre-defined encoding you specify.

Encoding	Space character	Hyphen character
html	 	‑
unicode	\u00a0	\u2011

For example:

preventWidows("lorem ipsum dolar sit a met", { encoding: Encodings.UNICODE });

Alternatively, a custom encoding can be defined using an object:

preventWidows("lorem ipsum dolar sit a met", {
  encoding: { space: "_", hyphen: "~" },
});

// lorem ipsum dolar sit a_met

posthtml

This module comes with optional support for posthtml.

Note: posthtml is listed as an optional peer dependency. If you only need to process strings, you don't need to install it.

Usage

The posthtml function exposes an additional parameter: posthtmlOptions.

import posthtml from "posthtml";
import preventWidows from "prevent-widows";

posthtml().use(preventWidows.posthtml(posthtmlOptions, preventWidowsOptions));

Example

import posthtml from "posthtml";
import preventWidows from "prevent-widows";

(async () => {
  const input = "<div prevent-widows>lorem ipsum dolar sit a met</div>";

  const { html } = await posthtml().use(preventWidows.posthtml()).process(input);

  console.log(html);
})();

// <div>lorem ipsum dolar sit a&nbsp;met</div>

posthtml Options

The posthtml method also comes with the following options:

attrName

The name of the attribute which identifies where widows should be prevented on its children.

• Since: 1.0.0
• Property is Optional
• Default value is: prevent-widows
• Validation rules:
  • Must be a valid HTML attribute name

<div prevent-widows>Prevent widows</div>

attrRemove

Whether or not to remove the attribute (see: attrName) from the element after the transform has been applied.

• Since: 1.0.0
• Property is Optional
• Default value is: true
• Validation rules:
  • Must be a boolean value: true or false

When true and by default, this will output:

<div>Prevent widows</div>

When false, this will output:

<div prevent-widows>Prevent widows</div>

License

MIT