0
# Tailwind CSS Typography
1

2
The official Tailwind CSS Typography plugin provides a set of `prose` classes for adding beautiful typographic defaults to vanilla HTML content. It automatically styles plain HTML from sources like Markdown renderers or CMSs with carefully tuned typography scales, spacing, and color themes.
3

4
## Package Information
5

6
- **Package Name**: @tailwindcss/typography
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -D @tailwindcss/typography`
10

11
## Core Imports
12

13
```javascript
14
const typographyPlugin = require('@tailwindcss/typography');
15
```
16

17
ESM:
18

19
```javascript
20
import typographyPlugin from '@tailwindcss/typography';
21
```
22

23
## Basic Usage
24

25
```javascript
26
// tailwind.config.js
27
module.exports = {
28
  theme: {
29
    // ...
30
  },
31
  plugins: [
32
    require('@tailwindcss/typography'),
33
    // ...
34
  ],
35
}
36
```
37

38
```html
39
<!-- Basic prose styling -->
40
<article class="prose">
41
  <h1>Article Title</h1>
42
  <p>Your HTML content gets beautiful typography automatically.</p>
43
</article>
44

45
<!-- With size and color modifiers -->
46
<article class="prose prose-lg prose-slate">
47
  <h1>Large slate-themed content</h1>
48
  <p>Automatically styled with larger typography and slate color theme.</p>
49
</article>
50
```
51

52
## Architecture
53

54
The plugin is built around several key components:
55

56
- **Plugin Function**: Main export that registers with Tailwind CSS using the `plugin.withOptions` pattern
57
- **Typography Styles**: Comprehensive style definitions for all HTML elements in multiple size scales
58
- **Color Themes**: Pre-built color themes for different gray scales and accent colors
59
- **Variant System**: Element-specific modifier classes for granular control
60
- **CSS Custom Properties**: Theme-aware custom properties for consistent styling
61

62
## Capabilities
63

64
### Plugin Registration
65

66
Registers the typography plugin with Tailwind CSS, adding prose utility classes and theme configuration.
67

68
```typescript { .api }
69
/**
70
 * Main plugin export that integrates with Tailwind CSS
71
 * @param options - Plugin configuration options
72
 * @returns Tailwind CSS plugin object with handler and configuration
73
 */
74
function plugin(options?: Partial<PluginOptions>): TailwindPlugin;
75

76
interface PluginOptions {
77
  /** Base class name for typography styles (default: 'prose') */
78
  className?: string;
79
  /** 
80
   * Targeting mode for CSS selectors (default: 'modern')
81
   * - 'modern': Uses modern CSS selectors with :where() and :is()
82
   * - 'legacy': Uses traditional CSS selectors for older browser compatibility
83
   */
84
  target?: 'modern' | 'legacy';
85
}
86

87
interface TailwindPlugin {
88
  /** The plugin handler function */
89
  handler: () => void;
90
  /** Marker indicating this is an options-based plugin */
91
  __isOptionsFunction: true;
92
}
93
```
94

95
### Size Modifiers
96

97
Typography scales that adjust the overall size and spacing of content for different contexts.
98

99
```typescript { .api }
100
// Available size modifier classes
101
type SizeModifiers = 
102
  | 'prose-sm'    // Small scale (14px base)
103
  | 'prose'       // Base scale (16px base) 
104
  | 'prose-lg'    // Large scale (18px base)
105
  | 'prose-xl'    // Extra large scale (20px base)
106
  | 'prose-2xl';  // Double extra large scale (24px base)
107
```
108

109
**Usage Examples:**
110

111
```html
112
<!-- Small typography for compact layouts -->
113
<article class="prose prose-sm">{{ content }}</article>
114

115
<!-- Large typography for featured content -->
116
<article class="prose prose-xl">{{ content }}</article>
117

118
<!-- Extra large typography for hero content -->
119
<article class="prose prose-2xl">{{ content }}</article>
120

121
<!-- Responsive typography scaling -->
122
<article class="prose md:prose-lg lg:prose-xl">{{ content }}</article>
123
```
124

125
### Color Themes
126

127
Pre-built color themes that provide consistent styling across light and dark modes.
128

129
```typescript { .api }
130
// Gray scale themes
131
type GrayScaleThemes = 
132
  | 'prose-gray'    // Default gray theme
133
  | 'prose-slate'   // Slate gray theme
134
  | 'prose-zinc'    // Zinc gray theme
135
  | 'prose-neutral' // Neutral gray theme
136
  | 'prose-stone';  // Stone gray theme
137

138
// Accent color themes (affects links only)
139
type AccentColorThemes = 
140
  | 'prose-red' | 'prose-orange' | 'prose-amber' | 'prose-yellow'
141
  | 'prose-lime' | 'prose-green' | 'prose-emerald' | 'prose-teal'
142
  | 'prose-cyan' | 'prose-sky' | 'prose-blue' | 'prose-indigo'
143
  | 'prose-violet' | 'prose-purple' | 'prose-fuchsia' | 'prose-pink' | 'prose-rose';
144

145
// Special themes
146
type SpecialThemes = 'prose-invert'; // Dark mode theme
147
```
148

149
**Usage Examples:**
150

151
```html
152
<!-- Slate color theme -->
153
<article class="prose prose-slate">{{ content }}</article>
154

155
<!-- Blue links with default gray theme -->
156
<article class="prose prose-blue">{{ content }}</article>
157

158
<!-- Dark mode styling -->
159
<article class="prose prose-invert">{{ content }}</article>
160

161
<!-- Combined themes -->
162
<article class="prose prose-lg prose-slate prose-blue">{{ content }}</article>
163
```
164

165
### Element Variants
166

167
Element-specific modifier classes for granular control over individual HTML elements.
168

169
```typescript { .api }
170
// Element-specific variant classes
171
type ElementVariants = 
172
  | 'prose-headings' // All headings (h1-h6, th)
173
  | 'prose-h1' | 'prose-h2' | 'prose-h3' | 'prose-h4' | 'prose-h5' | 'prose-h6'
174
  | 'prose-p'        // Paragraphs
175
  | 'prose-a'        // Links
176
  | 'prose-blockquote' // Block quotes
177
  | 'prose-figure' | 'prose-figcaption' // Figures and captions
178
  | 'prose-strong' | 'prose-em' // Text emphasis
179
  | 'prose-kbd' | 'prose-code' | 'prose-pre' // Code elements
180
  | 'prose-ol' | 'prose-ul' | 'prose-li' // Lists
181
  | 'prose-table' | 'prose-thead' | 'prose-tr' | 'prose-th' | 'prose-td' // Tables
182
  | 'prose-img' | 'prose-video' // Media
183
  | 'prose-hr'       // Horizontal rules
184
  | 'prose-lead';    // Lead text (class-based)
185
```
186

187
### Not-Prose Utility
188

189
Disables typography styles for specific content areas within prose-styled containers.
190

191
```typescript { .api }
192
// Utility class for disabling prose styles
193
type NotProseUtility = 'not-prose'; // Disables all prose styling for nested content
194
```
195

196
**Usage Examples:**
197

198
```html
199
<!-- Disable prose styles for a specific section -->
200
<article class="prose">
201
  <h1>Article Title</h1>
202
  <p>This paragraph has prose styling.</p>
203
  
204
  <div class="not-prose">
205
    <!-- This content is not styled by prose -->
206
    <div class="bg-blue-500 p-4 text-white">
207
      Custom styled content that ignores prose
208
    </div>
209
  </div>
210
  
211
  <p>This paragraph has prose styling again.</p>
212
</article>
213
```
214

215
```html
216
<!-- Style only headings with a specific color -->
217
<article class="prose prose-headings:text-blue-900">{{ content }}</article>
218

219
<!-- Style only links -->
220
<article class="prose prose-a:text-green-600 prose-a:no-underline">{{ content }}</article>
221
```
222

223
### Theme Configuration
224

225
The plugin provides a complete theme configuration for the `typography` key in Tailwind's theme.
226

227
```typescript { .api }
228
interface TypographyTheme {
229
  DEFAULT: TypographyConfig;
230
  sm: TypographyConfig;
231
  base: TypographyConfig;
232
  lg: TypographyConfig;
233
  xl: TypographyConfig;
234
  '2xl': TypographyConfig;
235
  // Color themes
236
  slate: TypographyConfig;
237
  gray: TypographyConfig;
238
  zinc: TypographyConfig;
239
  neutral: TypographyConfig;
240
  stone: TypographyConfig;
241
  // Accent color themes
242
  red: TypographyConfig;
243
  orange: TypographyConfig;
244
  // ... all other color themes
245
  invert: TypographyConfig;
246
}
247

248
interface TypographyConfig {
249
  css: CSSRule[] | CSSRule;
250
}
251

252
interface CSSRule {
253
  [selector: string]: CSSProperties | CSSRule;
254
}
255
```
256

257
## CSS Custom Properties
258

259
The plugin defines comprehensive CSS custom properties for consistent theming:
260

261
```css { .api }
262
/* Light mode properties */
263
--tw-prose-body: /* Body text color */
264
--tw-prose-headings: /* Heading text color */
265
--tw-prose-lead: /* Lead text color */
266
--tw-prose-links: /* Link color */
267
--tw-prose-bold: /* Bold text color */
268
--tw-prose-counters: /* List counter color */
269
--tw-prose-bullets: /* List bullet color */
270
--tw-prose-hr: /* Horizontal rule color */
271
--tw-prose-quotes: /* Blockquote text color */
272
--tw-prose-quote-borders: /* Blockquote border color */
273
--tw-prose-captions: /* Caption text color */
274
--tw-prose-kbd: /* Keyboard text color */
275
--tw-prose-kbd-shadows: /* Keyboard shadow color (RGB values) */
276
--tw-prose-code: /* Inline code color */
277
--tw-prose-pre-code: /* Code block text color */
278
--tw-prose-pre-bg: /* Code block background color */
279
--tw-prose-th-borders: /* Table header border color */
280
--tw-prose-td-borders: /* Table cell border color */
281

282
/* Dark mode properties (used with prose-invert) */
283
--tw-prose-invert-body: /* Inverted body text color */
284
--tw-prose-invert-headings: /* Inverted heading text color */
285
/* ... all other invert properties */
286
```
287

288
## Advanced Configuration
289

290
### Custom Theme Extension
291

292
```javascript
293
// tailwind.config.js
294
module.exports = {
295
  theme: {
296
    extend: {
297
      typography: {
298
        'custom': {
299
          css: {
300
            '--tw-prose-body': '#1a1a1a',
301
            '--tw-prose-headings': '#0f0f0f',
302
            // ... custom properties
303
          },
304
        },
305
      },
306
    },
307
  },
308
  plugins: [
309
    require('@tailwindcss/typography'),
310
  ],
311
}
312
```
313

314
### Plugin Options
315

316
```javascript
317
// tailwind.config.js
318
module.exports = {
319
  plugins: [
320
    require('@tailwindcss/typography')({
321
      className: 'wysiwyg',  // Use 'wysiwyg' instead of 'prose'
322
      target: 'legacy'       // Use legacy CSS selectors for older browsers
323
    }),
324
  ],
325
}
326
```
327

328
**Target Options:**
329

330
- **`modern` (default)**: Uses `:where()` and `:is()` pseudo-selectors for better specificity control and performance. Recommended for modern browsers.
331
- **`legacy`**: Uses traditional CSS selectors without modern pseudo-selectors. Use this if you need to support older browsers that don't support `:where()` and `:is()`.
332

333
```html
334
<!-- With custom className -->
335
<article class="wysiwyg wysiwyg-lg wysiwyg-slate">{{ content }}</article>
336
```
337

338
## Styled Elements
339

340
The plugin automatically styles all standard HTML elements commonly found in content:
341

342
- **Typography**: h1-h6, p, lead text
343
- **Emphasis**: strong, em, mark
344
- **Code**: code, pre, kbd
345
- **Lists**: ul, ol, li, dl, dt, dd
346
- **Links**: a
347
- **Quotes**: blockquote
348
- **Media**: img, video, picture
349
- **Tables**: table, thead, tbody, tfoot, tr, th, td
350
- **Misc**: hr, figure, figcaption
351

352
Each element receives carefully tuned spacing, typography, and color styles that work harmoniously together.