0
# Text Style Mark
1

2
The TextStyle mark is the foundational mark for all text styling operations in TipTap. It creates HTML span elements and provides the base functionality that other styling extensions build upon.
3

4
## Capabilities
5

6
### TextStyle Mark
7

8
Core ProseMirror mark that handles text styling through HTML span elements with advanced nested style parsing.
9

10
```typescript { .api }
11
/**
12
 * Core text style mark for HTML span element handling
13
 * Priority: 101 (high priority to ensure proper layering)
14
 */
15
const TextStyle: Mark<TextStyleOptions>;
16

17
interface TextStyleOptions {
18
  /** HTML attributes to add to the span element */
19
  HTMLAttributes: Record<string, any>;
20
  /** 
21
   * When enabled, merges styles of nested spans into child span during HTML parsing
22
   * Prioritizes the style of the child span, used when parsing content from other editors
23
   */
24
  mergeNestedSpanStyles: boolean;
25
}
26
```
27

28
**Usage Example:**
29

30
```typescript
31
import { Editor } from "@tiptap/core";
32
import { TextStyle } from "@tiptap/extension-text-style/text-style";
33

34
const editor = new Editor({
35
  extensions: [
36
    TextStyle.configure({
37
      HTMLAttributes: {
38
        class: "custom-text-style"
39
      },
40
      mergeNestedSpanStyles: true
41
    })
42
  ]
43
});
44
```
45

46
### Toggle Text Style Command
47

48
Apply or remove text styling attributes on the current selection.
49

50
```typescript { .api }
51
/**
52
 * Toggle text style attributes on the current selection
53
 * @param attributes - Text style attributes to apply or toggle off
54
 * @returns Command result indicating success/failure
55
 */
56
toggleTextStyle(attributes?: TextStyleAttributes): Command;
57
```
58

59
**Usage Example:**
60

61
```typescript
62
// Apply multiple attributes at once
63
editor.commands.toggleTextStyle({
64
  color: "#ff0000",
65
  fontSize: "18px",
66
  fontFamily: "Arial"
67
});
68

69
// Toggle off all styling
70
editor.commands.toggleTextStyle();
71
```
72

73
### Remove Empty Text Style Command
74

75
Clean up empty text style marks that have no meaningful attributes.
76

77
```typescript { .api }
78
/**
79
 * Remove spans without inline style attributes
80
 * Traverses selection and removes textStyle marks with no attribute values
81
 * @returns Command result indicating success/failure
82
 */
83
removeEmptyTextStyle(): Command;
84
```
85

86
**Usage Example:**
87

88
```typescript
89
// Clean up empty styling after removing attributes
90
editor.chain()
91
  .setMark("textStyle", { color: null })
92
  .removeEmptyTextStyle()
93
  .run();
94
```
95

96
## HTML Processing
97

98
### Parsing Behavior
99

100
The TextStyle mark includes sophisticated HTML parsing logic:
101

102
- **Span Detection**: Only processes `<span>` elements that have a `style` attribute
103
- **Nested Span Merging**: When `mergeNestedSpanStyles` is enabled, combines parent and child span styles with child taking priority
104
- **Style Priority**: Child span styles override parent span styles during parsing
105
- **Non-consuming**: Allows other marks to also process the same span element
106

107
### Rendering Behavior
108

109
- **Output Format**: Renders as `<span>` elements with merged HTML attributes
110
- **Attribute Merging**: Combines extension HTMLAttributes with dynamic attributes
111
- **Clean Output**: Only renders spans when meaningful style attributes are present
112

113
## Integration Notes
114

115
### Extension Dependencies
116

117
Most styling extensions depend on TextStyle:
118

119
```typescript
120
// Styling extensions import TextStyle
121
import '../text-style/index.js'
122
```
123

124
### Command System Integration
125

126
TextStyle integrates with TipTap's command system through module augmentation:
127

128
```typescript
129
declare module '@tiptap/core' {
130
  interface Commands<ReturnType> {
131
    textStyle: {
132
      removeEmptyTextStyle: () => ReturnType;
133
      toggleTextStyle: (attributes?: TextStyleAttributes) => ReturnType;
134
    }
135
  }
136
}
137
```
138

139
### Type System Integration
140

141
Extends the TextStyleAttributes interface for use by other extensions:
142

143
```typescript
144
import type { TextStyleAttributes } from '../index.js';
145
```