0
# Title Case
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: title-case
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install title-case`
10

11
## Core Imports
12

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

15
```typescript
16
import { 
17
  titleCase, 
18
  Options,
19
  WORD_SEPARATORS,
20
  SENTENCE_TERMINATORS, 
21
  TITLE_TERMINATORS,
22
  SMALL_WORDS 
23
} from "title-case";
24
```
25

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

28
## Basic Usage
29

30
```typescript
31
import { titleCase } from "title-case";
32

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

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

40
// Sentence case mode
41
titleCase("one sentence. two sentences.", { sentenceCase: true }); 
42
// "One sentence. Two sentences."
43
```
44

45
## Capabilities
46

47
### Title Case Transformation
48

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

51
```typescript { .api }
52
/**
53
 * Transform a string into title case following English rules
54
 * @param input - The string to transform
55
 * @param options - Configuration options or locale string/array
56
 * @returns The transformed title case string
57
 */
58
function titleCase(
59
  input: string,
60
  options: Options | string[] | string = {}
61
): string;
62

63
interface Options {
64
  /** Locale used for toLocaleUpperCase during case transformation */
65
  locale?: string | string[];
66
  /** Only capitalize the first word of each sentence (default: false) */
67
  sentenceCase?: boolean;
68
  /** Set of characters to consider a new sentence under sentence case behavior */
69
  sentenceTerminators?: Set<string>;
70
  /** Set of words to keep lower-case when sentenceCase === false */
71
  smallWords?: Set<string>;
72
  /** Set of characters to consider a new sentence under title case behavior */
73
  titleTerminators?: Set<string>;
74
  /** Set of characters to consider a new word for capitalization, such as hyphenation */
75
  wordSeparators?: Set<string>;
76
}
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
import { titleCase, SMALL_WORDS } from "title-case";
83

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

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

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

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

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

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

109
### Configuration Constants
110

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

113
```typescript { .api }
114
/** Default word separator characters: "—", "–", "-", "―", "/" */
115
const WORD_SEPARATORS: Set<string>;
116

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

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

123
/** Default small words that remain lowercase in title case */
124
const SMALL_WORDS: Set<string>;
125
```
126

127
The `SMALL_WORDS` set includes common English articles, prepositions, and conjunctions:
128
- Articles: "a", "an", "the"
129
- Prepositions: "at", "by", "for", "in", "of", "on", "to", "up", "with", etc.
130
- Conjunctions: "and", "but", "or", "nor", "yet"
131
- Others: "as", "if", "so", "than", "that", "when", etc.
132

133
**Usage Examples:**
134

135
```typescript
136
import { 
137
  titleCase, 
138
  SMALL_WORDS, 
139
  WORD_SEPARATORS, 
140
  TITLE_TERMINATORS 
141
} from "title-case";
142

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

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

149
// Custom configuration
150
titleCase("connect via ethernet|wifi per requirements", {
151
  smallWords: extendedSmallWords,
152
  wordSeparators: customSeparators
153
}); // "Connect via Ethernet|Wifi per Requirements"
154
```
155

156
## Special Features
157

158
### Intelligent Case Preservation
159

160
Title Case intelligently preserves existing casing in special scenarios:
161

162
- **URLs and Email Addresses**: `example.com`, `user@domain.com` remain unchanged
163
- **Manual Casing**: `iPhone`, `iOS`, `jQuery` preserve their specific capitalization
164
- **Acronyms**: `U.S.A.`, `N.A.S.A.` are handled appropriately
165

166
### Advanced Grammar Rules
167

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

173
### Error Handling
174

175
The function handles edge cases gracefully:
176
- Empty strings return empty strings
177
- Null/undefined inputs may cause TypeScript compilation errors (as intended)
178
- Invalid characters are processed without throwing errors
179
- Malformed input preserves as much structure as possible