0
# Text and Document Analysis
1

2
The Character Count extension provides comprehensive text and document analysis capabilities, including character counting, word counting, and content limit enforcement.
3

4
## Capabilities
5

6
### Character Count Extension
7

8
Tracks character and word counts in the document with optional limits and custom counting functions.
9

10
```typescript { .api }
11
/**
12
 * Character count extension with limit enforcement and custom counting functions
13
 */
14
const CharacterCount: Extension<CharacterCountOptions, CharacterCountStorage>;
15

16
interface CharacterCountOptions {
17
  /** Maximum number of characters allowed (default: null) */
18
  limit: number | null | undefined;
19
  /** Counting mode: 'textSize' uses textContent, 'nodeSize' uses nodeSize (default: 'textSize') */
20
  mode: 'textSize' | 'nodeSize';
21
  /** Custom text counter function (default: text => text.length) */
22
  textCounter: (text: string) => number;
23
  /** Custom word counter function (default: word splitting on spaces) */
24
  wordCounter: (text: string) => number;
25
}
26

27
interface CharacterCountStorage {
28
  /** Get character count for the current document or specified node */
29
  characters: (options?: { 
30
    node?: ProsemirrorNode; 
31
    mode?: 'textSize' | 'nodeSize' 
32
  }) => number;
33
  /** Get word count for the current document or specified node */
34
  words: (options?: { node?: ProsemirrorNode }) => number;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { Editor } from "@tiptap/core";
42
import { CharacterCount } from "@tiptap/extensions/character-count";
43

44
// Basic character counting
45
const editor = new Editor({
46
  extensions: [
47
    CharacterCount.configure({
48
      limit: 280, // Twitter-like limit
49
    }),
50
  ],
51
});
52

53
// Access counts
54
const characterCount = editor.storage.characterCount.characters();
55
const wordCount = editor.storage.characterCount.words();
56

57
console.log(`Characters: ${characterCount}, Words: ${wordCount}`);
58

59
// Custom counting functions
60
const editorWithCustomCounting = new Editor({
61
  extensions: [
62
    CharacterCount.configure({
63
      limit: 1000,
64
      textCounter: (text) => {
65
        // Count using internationalization-aware segmenter
66
        return [...new Intl.Segmenter().segment(text)].length;
67
      },
68
      wordCounter: (text) => {
69
        // Custom word splitting
70
        return text.split(/\s+/).filter(word => word !== '').length;
71
      },
72
    }),
73
  ],
74
});
75

76
// Count specific node
77
const specificNode = editor.state.doc.firstChild;
78
const nodeCharacters = editor.storage.characterCount.characters({ 
79
  node: specificNode 
80
});
81
```
82

83
### Character Counting Modes
84

85
The extension supports two counting modes:
86

87
**Text Size Mode (default):**
88
- Uses `textContent` of the document
89
- Counts actual visible text characters
90
- Respects custom `textCounter` function
91

92
**Node Size Mode:**
93
- Uses ProseMirror's `nodeSize` property
94
- Includes structural elements and marks
95
- More comprehensive for document structure analysis
96

97
```typescript
98
// Text size mode (default)
99
CharacterCount.configure({
100
  mode: 'textSize', // Counts visible text only
101
});
102

103
// Node size mode
104
CharacterCount.configure({
105
  mode: 'nodeSize', // Includes document structure
106
});
107
```
108

109
### Content Limit Enforcement
110

111
When a limit is set, the extension automatically:
112

113
1. **Initial Content Trimming**: Automatically trims content that exceeds the limit on initialization
114
2. **Transaction Filtering**: Blocks transactions that would exceed the limit
115
3. **Paste Handling**: Intelligently truncates pasted content to fit within limits
116
4. **Complex Node Handling**: Properly handles limits within complex structures like tables
117

118
```typescript
119
import { CharacterCount } from "@tiptap/extensions/character-count";
120

121
const editor = new Editor({
122
  extensions: [
123
    CharacterCount.configure({
124
      limit: 500,
125
      mode: 'textSize',
126
    }),
127
  ],
128
  content: 'Initial content...',
129
});
130

131
// The extension will automatically prevent content that exceeds 500 characters
132
// and will trim pasted content to fit within the limit
133
```
134

135
### Module Declarations
136

137
```typescript { .api }
138
declare module '@tiptap/core' {
139
  interface Storage {
140
    characterCount: CharacterCountStorage;
141
  }
142
}
143
```
144

145
The extension adds its storage interface to the global Tiptap storage, making character and word counting methods available on any editor instance that includes this extension.