0
# Color Styling
1

2
The Color extension provides text color styling capabilities with robust HTML parsing that preserves original color formats and handles nested span elements.
3

4
## Capabilities
5

6
### Color Extension
7

8
Extension for applying text color with support for any CSS color format and advanced HTML style parsing.
9

10
```typescript { .api }
11
/**
12
 * Extension for setting text color on specified node types
13
 * Extends textStyle mark with color attribute
14
 */
15
const Color: Extension<ColorOptions>;
16

17
interface ColorOptions {
18
  /** 
19
   * Node types where color can be applied
20
   * @default ['textStyle']
21
   * @example ['heading', 'paragraph', 'textStyle']
22
   */
23
  types: string[];
24
}
25
```
26

27
**Usage Example:**
28

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

34
const editor = new Editor({
35
  extensions: [
36
    TextStyle, // Required dependency
37
    Color.configure({
38
      types: ['textStyle', 'heading']
39
    })
40
  ]
41
});
42
```
43

44
### Set Color Command
45

46
Apply a specific color to the current text selection.
47

48
```typescript { .api }
49
/**
50
 * Set the text color
51
 * @param color - CSS color value (hex, rgb, hsl, named colors, etc.)
52
 * @returns Command result indicating success/failure
53
 */
54
setColor(color: string): Command;
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
// Hex colors
61
editor.commands.setColor("#ff0000");
62
editor.commands.setColor("#c0ffee");
63

64
// RGB/RGBA colors
65
editor.commands.setColor("rgb(255, 0, 0)");
66
editor.commands.setColor("rgba(255, 0, 0, 0.5)");
67

68
// HSL colors
69
editor.commands.setColor("hsl(120, 100%, 50%)");
70

71
// Named colors
72
editor.commands.setColor("red");
73
editor.commands.setColor("darkblue");
74

75
// Chain with other commands
76
editor.chain()
77
  .setColor("#0066cc")
78
  .setFontSize("18px")
79
  .run();
80
```
81

82
### Unset Color Command
83

84
Remove color styling from the current text selection.
85

86
```typescript { .api }
87
/**
88
 * Unset the text color, removing color attribute and cleaning up empty textStyle marks
89
 * @returns Command result indicating success/failure
90
 */
91
unsetColor(): Command;
92
```
93

94
**Usage Example:**
95

96
```typescript
97
// Remove color and clean up empty styling
98
editor.commands.unsetColor();
99

100
// Chain removal with other operations
101
editor.chain()
102
  .unsetColor()
103
  .setFontFamily("Arial")
104
  .run();
105
```
106

107
## HTML Processing
108

109
### Advanced Color Parsing
110

111
The Color extension includes sophisticated HTML parsing that:
112

113
- **Preserves Format**: Maintains original color format from HTML (`#rrggbb` vs `rgb(...)`)
114
- **Handles Nested Spans**: When multiple color declarations exist in nested spans, child color takes priority
115
- **Multiple Declarations**: Parses style attributes with multiple `color:` declarations, using the last one
116
- **Quote Handling**: Automatically removes quotes from color values during parsing
117

118
### Parsing Priority Logic
119

120
```typescript
121
// Example of nested span parsing
122
// <span style="color: blue;"><span style="color: red;">text</span></span>
123
// Result: color will be "red" (child takes priority)
124
```
125

126
### Rendering Output
127

128
- **CSS Format**: Renders as `style="color: {value}"` attribute
129
- **Clean Output**: Only adds color attribute when a color value is present
130
- **Format Preservation**: Maintains original color format when possible
131

132
## Type System Integration
133

134
### Module Augmentation
135

136
The Color extension augments TipTap's type system:
137

138
```typescript
139
// Extends core Commands interface
140
declare module '@tiptap/core' {
141
  interface Commands<ReturnType> {
142
    color: {
143
      setColor: (color: string) => ReturnType;
144
      unsetColor: () => ReturnType;
145
    }
146
  }
147
}
148

149
// Extends TextStyleAttributes interface  
150
declare module '@tiptap/extension-text-style' {
151
  interface TextStyleAttributes {
152
    color?: string | null;
153
  }
154
}
155
```
156

157
## Configuration Examples
158

159
### Basic Configuration
160

161
```typescript
162
import { Color } from "@tiptap/extension-text-style/color";
163

164
const colorExtension = Color.configure({
165
  types: ['textStyle']
166
});
167
```
168

169
### Extended Node Type Support
170

171
```typescript
172
const colorExtension = Color.configure({
173
  types: ['textStyle', 'heading', 'paragraph']
174
});
175
```
176

177
This allows color to be applied directly to headings and paragraphs in addition to inline text styling.