0
# @tiptap/extension-subscript
1

2
The @tiptap/extension-subscript package provides subscript text formatting functionality for TipTap rich text editors. This extension allows users to create subscript text with keyboard shortcuts, programmatic commands, and automatic HTML parsing/rendering.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-subscript
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-subscript`
10
- **Peer Dependencies**: `@tiptap/core`, `@tiptap/pm`
11

12
## Core Imports
13

14
```typescript
15
import { Subscript, SubscriptExtensionOptions } from '@tiptap/extension-subscript';
16
```
17

18
Default import:
19

20
```typescript
21
import Subscript from '@tiptap/extension-subscript';
22
```
23

24
CommonJS:
25

26
```javascript
27
const { Subscript } = require('@tiptap/extension-subscript');
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Editor } from '@tiptap/core';
34
import Subscript from '@tiptap/extension-subscript';
35

36
// Create editor with subscript extension
37
const editor = new Editor({
38
  extensions: [
39
    Subscript.configure({
40
      HTMLAttributes: {
41
        class: 'my-subscript',
42
      },
43
    }),
44
  ],
45
  content: '<p>H<sub>2</sub>O is water</p>',
46
});
47

48
// Use programmatic commands
49
editor.commands.toggleSubscript();
50
editor.commands.setSubscript();
51
editor.commands.unsetSubscript();
52

53
// Use keyboard shortcut: Mod-,
54
```
55

56
## Capabilities
57

58
### Extension Class
59

60
The main extension class that creates subscript functionality in TipTap editors.
61

62
```typescript { .api }
63
/**
64
 * TipTap Mark extension that provides subscript text formatting
65
 */
66
declare const Subscript: Mark<SubscriptExtensionOptions>;
67
```
68

69
### Configuration Options
70

71
Options interface for configuring the subscript extension.
72

73
```typescript { .api }
74
interface SubscriptExtensionOptions {
75
  /**
76
   * HTML attributes to add to the subscript element.
77
   * @default {}
78
   * @example { class: 'foo' }
79
   */
80
  HTMLAttributes: Record<string, any>;
81
}
82
```
83

84
### Commands
85

86
Commands added to the TipTap editor for manipulating subscript marks.
87

88
```typescript { .api }
89
interface Commands<ReturnType> {
90
  subscript: {
91
    /**
92
     * Set a subscript mark on the current selection
93
     * @example editor.commands.setSubscript()
94
     */
95
    setSubscript: () => ReturnType;
96
    
97
    /**
98
     * Toggle a subscript mark on the current selection
99
     * @example editor.commands.toggleSubscript()
100
     */
101
    toggleSubscript: () => ReturnType;
102
    
103
    /**
104
     * Remove subscript mark from the current selection
105
     * @example editor.commands.unsetSubscript()
106
     */
107
    unsetSubscript: () => ReturnType;
108
  };
109
}
110
```
111

112
## HTML Parsing and Rendering
113

114
### Supported HTML Input
115

116
The extension automatically parses:
117

118
- `<sub>` HTML tags: `H<sub>2</sub>O`
119
- CSS `vertical-align: sub` styles: `<span style="vertical-align: sub">2</span>`
120

121
### HTML Output
122

123
All subscript content is rendered as `<sub>` elements with merged HTML attributes:
124

125
```html
126
<sub class="my-subscript">2</sub>
127
```
128

129
## Keyboard Shortcuts
130

131
- **Mod-,** (Cmd+, on Mac, Ctrl+, on Windows/Linux): Toggles subscript formatting on the current selection
132

133
## Usage Examples
134

135
### Basic Subscript Formatting
136

137
```typescript
138
import { Editor } from '@tiptap/core';
139
import Subscript from '@tiptap/extension-subscript';
140

141
const editor = new Editor({
142
  extensions: [Subscript],
143
  content: 'Type H2O and select the 2, then press Cmd-,',
144
});
145

146
// Programmatically apply subscript
147
editor.chain().focus().setSubscript().run();
148
```
149

150
### Custom HTML Attributes
151

152
```typescript
153
const editor = new Editor({
154
  extensions: [
155
    Subscript.configure({
156
      HTMLAttributes: {
157
        class: 'subscript-text',
158
        'data-type': 'subscript',
159
      },
160
    }),
161
  ],
162
});
163
```
164

165
### Chemical Formulas and Mathematical Notation
166

167
```typescript
168
// Perfect for scientific content
169
const chemistryEditor = new Editor({
170
  extensions: [Subscript],
171
  content: `
172
    <p>Water: H<sub>2</sub>O</p>
173
    <p>Carbon dioxide: CO<sub>2</sub></p>
174
    <p>Mathematical notation: x<sub>n</sub></p>
175
  `,
176
});
177
```
178

179
## Types
180

181
```typescript { .api }
182
interface SubscriptExtensionOptions {
183
  /**
184
   * HTML attributes to add to the subscript element.
185
   * @default {}
186
   * @example { class: 'foo' }
187
   */
188
  HTMLAttributes: Record<string, any>;
189
}
190

191
type ReturnType = boolean;
192

193
interface Mark<T = any> {
194
  create<O extends Record<string, any>>(config: any): Mark<O>;
195
  configure(options?: Partial<T>): Mark<T>;
196
}
197
```