or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-title-case

Transform a string into title case following English rules

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/title-case@4.3.x

To install, run

npx @tessl/cli install tessl/npm-title-case@4.3.0

index.mddocs/

Title Case

Title Case transforms strings into proper title case following English grammar rules. It handles complex scenarios like hyphenated words, small words, acronyms, URLs, and preserves manual casing (e.g., "iPhone", "iOS") while providing extensive configuration options for different capitalization needs.

Package Information

  • Package Name: title-case
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install title-case

Core Imports

This is a pure ESM package and must be imported using ES module syntax:

import { 
  titleCase, 
  Options,
  WORD_SEPARATORS,
  SENTENCE_TERMINATORS, 
  TITLE_TERMINATORS,
  SMALL_WORDS 
} from "title-case";

Note: This package cannot be used with require() or CommonJS module resolution. It is ESM-only.

Basic Usage

import { titleCase } from "title-case";

// Simple transformation
titleCase("hello world"); // "Hello World"
titleCase("follow step-by-step instructions"); // "Follow Step-by-Step Instructions"

// With locale support
titleCase("piña colada", "en-US"); // "Piña Colada"

// Sentence case mode
titleCase("one sentence. two sentences.", { sentenceCase: true }); 
// "One sentence. Two sentences."

Capabilities

Title Case Transformation

Transforms input strings into proper title case following English grammar rules with intelligent handling of special cases.

/**
 * Transform a string into title case following English rules
 * @param input - The string to transform
 * @param options - Configuration options or locale string/array
 * @returns The transformed title case string
 */
function titleCase(
  input: string,
  options: Options | string[] | string = {}
): string;

interface Options {
  /** Locale used for toLocaleUpperCase during case transformation */
  locale?: string | string[];
  /** Only capitalize the first word of each sentence (default: false) */
  sentenceCase?: boolean;
  /** Set of characters to consider a new sentence under sentence case behavior */
  sentenceTerminators?: Set<string>;
  /** Set of words to keep lower-case when sentenceCase === false */
  smallWords?: Set<string>;
  /** Set of characters to consider a new sentence under title case behavior */
  titleTerminators?: Set<string>;
  /** Set of characters to consider a new word for capitalization, such as hyphenation */
  wordSeparators?: Set<string>;
}

Usage Examples:

import { titleCase, SMALL_WORDS } from "title-case";

// Basic title case
titleCase("the quick brown fox"); // "The Quick Brown Fox"

// Preserves special cases
titleCase("visit example.com for more info"); // "Visit example.com for More Info"
titleCase("iPhone and iOS development"); // "iPhone and iOS Development"

// Handles hyphenated words
titleCase("state-of-the-art technology"); // "State-of-the-Art Technology"

// Custom small words
const customSmallWords = new Set([...SMALL_WORDS, "via", "per"]);
titleCase("send via email per instructions", { 
  smallWords: customSmallWords 
}); // "Send via Email per Instructions"

// Sentence case mode
titleCase("first sentence. second sentence! third sentence?", {
  sentenceCase: true
}); // "First sentence. Second sentence! Third sentence?"

// Locale-specific capitalization
titleCase("straße in münchen", "de-DE"); // "Straße in München"

Configuration Constants

Pre-defined sets of characters and words for common title case scenarios.

/** Default word separator characters: "—", "–", "-", "―", "/" */
const WORD_SEPARATORS: Set<string>;

/** Default sentence terminator characters: ".", "!", "?" */
const SENTENCE_TERMINATORS: Set<string>;

/** Default title terminator characters: includes sentence terminators plus ":", '"', "'", """ */
const TITLE_TERMINATORS: Set<string>;

/** Default small words that remain lowercase in title case */
const SMALL_WORDS: Set<string>;

The SMALL_WORDS set includes common English articles, prepositions, and conjunctions:

  • Articles: "a", "an", "the"
  • Prepositions: "at", "by", "for", "in", "of", "on", "to", "up", "with", etc.
  • Conjunctions: "and", "but", "or", "nor", "yet"
  • Others: "as", "if", "so", "than", "that", "when", etc.

Usage Examples:

import { 
  titleCase, 
  SMALL_WORDS, 
  WORD_SEPARATORS, 
  TITLE_TERMINATORS 
} from "title-case";

// Extend default small words
const extendedSmallWords = new Set([...SMALL_WORDS, "via", "per"]);

// Custom word separators
const customSeparators = new Set([...WORD_SEPARATORS, "|", "\\"]);

// Custom configuration
titleCase("connect via ethernet|wifi per requirements", {
  smallWords: extendedSmallWords,
  wordSeparators: customSeparators
}); // "Connect via Ethernet|Wifi per Requirements"

Special Features

Intelligent Case Preservation

Title Case intelligently preserves existing casing in special scenarios:

  • URLs and Email Addresses: example.com, user@domain.com remain unchanged
  • Manual Casing: iPhone, iOS, jQuery preserve their specific capitalization
  • Acronyms: U.S.A., N.A.S.A. are handled appropriately

Advanced Grammar Rules

  • Small Words: Articles, prepositions, and conjunctions remain lowercase except at sentence boundaries
  • Hyphenated Words: Each segment is capitalized appropriately: state-of-the-art
  • Sentence Boundaries: First word after sentence terminators is always capitalized
  • Multi-language Support: Uses toLocaleUpperCase() for proper locale-specific capitalization

Error Handling

The function handles edge cases gracefully:

  • Empty strings return empty strings
  • Null/undefined inputs may cause TypeScript compilation errors (as intended)
  • Invalid characters are processed without throwing errors
  • Malformed input preserves as much structure as possible