TitleCaser

A style-guide–aware title case engine for JavaScript that implements AP, APA, Chicago, NYT, Wikipedia, and British styles with contextual acronym disambiguation and 1,000+ curated domain terms.

Links

• Demo
• CodePen Demo 1
• CodePen Demo 2
• Contributing
• Changelog
• License

Introduction

TitleCaser is a deterministic, style-guide–aware title casing engine built for production publishing systems. It implements major editorial standards with rule-driven capitalization logic, including contextual acronym disambiguation, compound handling, possessive normalization, punctuation-aware processing, and curated domain vocabulary enforcement across marketing, academia, business, finance, geography, legal, defense, and technology.

Its multi-pass processing architecture ensures deterministic output while supporting custom overrides, exact phrase preservation, and controlled vocabulary enforcement. Designed for Node.js and browser environments, TitleCaser integrates cleanly into CMS pipelines, build systems, and automated editorial workflows where precision and repeatability are required.

Key Features

Multi-Style Editorial Engine

Built-in rule systems for AP, APA, Chicago, NYT, Wikipedia (sentence case), and British styles. Each style applies its own logic for minor words, hyphenated compounds, possessives, colon capitalization, and acronym handling, producing consistent, repeatable output.

Contextual Acronym & Pronoun Disambiguation

Distinguishes regional acronyms from identical lowercase words using positional and surrounding-word heuristics.

For example:

"It’s up to us in the US military to decide."
→ "It’s Up to Us in the US Military to Decide."

"us-uk-led coalition"
→ "US-UK-Led Coalition"

• Supports US, UK, EU, USA (dotted and undotted forms)
• Handles hyphenated compounds (US-Backed, US-UK-Led)
• Works in parenthetical and comma-separated contexts
• Detects end-of-sentence acronyms
• Avoids false positives inside longer words

Structured Vocabulary Normalization

Includes 1,000+ curated normalization rules across brands, technology, geography, business, marketing, defense, academia, finance, and legal domains.

• Mixed-case normalization (GOOGle → Google)
• Intentional lowercase brands (iPhone, eBay)
• Roman numerals (Louis-IV)
• Unicode names (Škoda)
• Possessive handling (GOOGle's tensorflow → Google's TensorFlow)
• Runtime custom term overrides
• Exact phrase replacements

Advanced Hyphenation & Compound Handling

Intelligent processing of hyphenated compounds with style-specific rules:

• Multi-hyphen compounds (US-UK-Led Coalition)
• Style-specific compound rules (AP vs Chicago)
• En dash and em dash normalization
• Acronym-first compound logic
• Roman numerals inside compounds
• Brand casing preservation inside compounds

Multi-Pass Deterministic Processing

Layered multi-pass processing for stable handling of complex inputs:

• Input normalization (spacing and <br> handling)
• Token-based whitespace-preserving transformation pipeline
• Style-aware casing pass
• Acronym resolution pass
• Short-word correction pass
• Final contextual correction pass
• Optional smart quote conversion
• Exact phrase override pass

HTML-Safe & CMS-Ready

Designed for integration into publishing workflows, CMS pipelines, and automated editorial systems.

• Preserves <br> tags
• Normalizes spacing around colon + <br>
• Retains ampersands and symbols
• Handles excessive whitespace safely
• Optional whitespace preservation for editor-safe real-time usage

Runtime & Build Support

The AMD/browser build extends String.prototype.toTitleCase() for direct string usage in client environments.

• Node.js (ES modules)
• Browser (prototype extension via AMD build)
• AMD distribution build
• CLI build and test scripts

Quick Start

npm install @danielhaim/titlecaser

import { TitleCaser } from '@danielhaim/titlecaser';

const titleCaser = new TitleCaser({ style: 'ap' });

titleCaser.toTitleCase('the quick brown fox'); // → "The Quick Brown Fox"
titleCaser.toTitleCase('nodejs development on aws'); // → "Node.js Development on AWS"
titleCaser.toTitleCase('let us know about the us military'); // → "Let Us Know About the US Military"

Core Usage

Editorial-Grade Transformation (AP Example)

Handles brand normalization, acronyms, hyphenation, possessives, and colon rules:

import { TitleCaser } from '@danielhaim/titlecaser';

const titleCaser = new TitleCaser({ style: 'ap' });

titleCaser.toTitleCase(
  "nodejs development on aws: an in-depth tutorial on server-side javascript deployment"
); // → "Node.js Development on AWS: An In-depth Tutorial on Server-side JavaScript Deployment"

Custom Term Normalization

titleCaser.addReplaceTerm('js', 'JavaScript');
titleCaser.toTitleCase('js development'); // → "JavaScript Development"

Exact Phrase Replacement

titleCaser.addExactPhraseReplacements([
  { 'the correct phrase': 'The Correct Phrase' }
]);

titleCaser.toTitleCase('this is the correct phrase'); // → "This Is The Correct Phrase"

Smart Quotes

const tc = new TitleCaser({
  style: 'ap',
  smartQuotes: true
});

tc.toTitleCase('"never underestimate the power o\' persistence,"'); // → “Never Underestimate the Power O’ Persistence,”

Whitespace Normalization

Whitespace normalization is enabled by default.

By default, TitleCaser collapses consecutive whitespace and trims leading and trailing spaces:

const tc = new TitleCaser({ style: "ap" });

tc.toTitleCase("   the   quick   brown   fox   "); // → "The Quick Brown Fox"

For real-time editors or environments where spacing must be preserved, disable normalization:

const tc = new TitleCaser({
  style: "ap",
  normalizeWhitespace: false
});

tc.toTitleCase("   the   quick   brown   fox   "); // → "   The   Quick   Brown   Fox   "

When normalizeWhitespace is false:

• Internal spacing is preserved
• Leading/trailing whitespace is preserved
• Newlines and tabs are preserved
• Only letter casing is transformed

This behavior allows safe integration into real-time editors without unexpected trimming or cursor instability when normalization is disabled (see Issue #17 for discussion).

Browser Usage

<script src="./path/to/TitleCaser.amd.js"></script>

const output = "the future of devops: the next era"
  .toTitleCase({ style: 'apa' });

console.log(output); // → "The Future of DevOps: The Next Era"

Real-World DOM Example

Automatically normalize editorial headings in a publishing workflow:

<h2>nodejs development on aws: an in-depth tutorial on server-side javascript deployment</h2>
<h2>the iphone's impact on modern communication: a sociolinguistic analysis</h2>
<h2>back-end and front-end</h2>

function applyTitleCaseToH2Elements(options = { style: "apa" }) {
  const h2Elements = document.querySelectorAll("h2");

  h2Elements.forEach((h2) => {
    h2.innerHTML = h2.innerHTML.toTitleCase(options);
  });
}

applyTitleCaseToH2Elements();

API Reference

Constructor

new TitleCaser(options)

Options

| Option | Type | Default | Description | |------------------------|------------|---------|-------------| | style | string | 'ap' | Editorial style: 'ap' \| 'apa' \| 'chicago' \| 'nyt' \| 'wikipedia' \| 'british' | | smartQuotes | boolean | false | Converts straight quotes (' ") to typographic curly quotes | | neverCapitalize | string[] | [] | Additional words that should remain lowercase (merged with style defaults) | | wordReplacementsList | object[] | internal defaults | Array of { 'term': 'replacement' } objects used for term normalization | | debug | boolean | false | Enables internal warning logs during processing | | normalizeWhitespace | boolean | true | Collapses consecutive whitespace and trims leading/trailing whitespace. Set to false to preserve original spacing (editor-safe mode). |

Methods

toTitleCase(text)

titleCaser.toTitleCase('hello world'); // → "Hello World"

addReplaceTerm(term, replacement)

titleCaser.addReplaceTerm('js', 'JavaScript');

removeReplaceTerm(term)

titleCaser.removeReplaceTerm('js');

setReplaceTerms(terms)

titleCaser.setReplaceTerms([
  { 'js': 'JavaScript' },
  { 'aws': 'AWS' }
]);

addExactPhraseReplacements(phrases)

titleCaser.addExactPhraseReplacements([
  { 'the correct phrase': 'The Correct Phrase' },
  { 'another phrase': 'Another Phrase' }
]);

setStyle(style)

titleCaser.setStyle('chicago');

Test Coverage

npm run test

• Extensive unit test coverage
• Cross-style validation (AP, Chicago, APA, NYT, Wikipedia)
• Acronym disambiguation edge cases
• Hyphenation edge cases
• Brand normalization

Resources

Useful materials for improving your knowledge of writing and language style guides. These resources include various books and manuals, such as the Publication Manual of the American Psychological Association, the Chicago Manual of Style, and the AP Stylebook, which are widely recognized as authoritative sources on grammar, punctuation, and capitalization rules.

• AP Stylebook, 56th Edition
• Publication Manual of the American Psychological Association, Seventh Edition (2020)
• Chicago Manual of Style: Capitalization
• The Bluebook: A Uniform System of Citation. 21st ed. Cambridge: Harvard Law Review Association, 2020
• The Chicago Manual of Style, 17th Edition
• The New York Times Manual of Style and Usage
• Wikipedia: Letter case
• Wikipedia:Manual of Style/Titles of works

Report Bugs

If you encounter any bugs or issues while using the library or the demo page, please report them by opening a new issue in the repository's issue tracker.

When reporting a bug, please provide as much detail as possible, including the steps to reproduce the issue and any error messages that you see. I appreciate any contribution to improving this library.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.