0
# Background Color Styling
1

2
The BackgroundColor extension provides background color styling capabilities with advanced HTML parsing that handles nested span elements and preserves original color formats.
3

4
## Capabilities
5

6
### BackgroundColor Extension
7

8
Extension for applying background colors to text with sophisticated CSS parsing and nested span support.
9

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

17
interface BackgroundColorOptions {
18
  /** 
19
   * Node types where background 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 { BackgroundColor } from "@tiptap/extension-text-style/background-color";
32
import { TextStyle } from "@tiptap/extension-text-style/text-style";
33

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

44
### Set Background Color Command
45

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

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

57
**Usage Examples:**
58

59
```typescript
60
// Hex colors
61
editor.commands.setBackgroundColor("#ffff00");
62
editor.commands.setBackgroundColor("#f0f8ff");
63

64
// RGB/RGBA colors
65
editor.commands.setBackgroundColor("rgb(255, 255, 0)");
66
editor.commands.setBackgroundColor("rgba(240, 248, 255, 0.8)");
67

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

71
// Named colors
72
editor.commands.setBackgroundColor("yellow");
73
editor.commands.setBackgroundColor("lightcyan");
74

75
// Chain with other styling commands
76
editor.chain()
77
  .setBackgroundColor("#ffffcc")
78
  .setColor("#333333")
79
  .run();
80
```
81

82
### Unset Background Color Command
83

84
Remove background color styling from the current text selection.
85

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

94
**Usage Example:**
95

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

100
// Chain removal with other operations
101
editor.chain()
102
  .unsetBackgroundColor()
103
  .setColor("#000000")
104
  .run();
105
```
106

107
## HTML Processing
108

109
### Advanced Background Color Parsing
110

111
The BackgroundColor extension includes sophisticated HTML parsing that:
112

113
- **Preserves Format**: Maintains original background-color format from HTML
114
- **Handles Nested Spans**: When multiple background-color declarations exist in nested spans, child background color takes priority
115
- **Multiple Declarations**: Parses style attributes with multiple `background-color:` declarations, using the last one
116
- **Quote Handling**: Automatically removes quotes from color values during parsing
117
- **CSS Property Priority**: Searches for `background-color:` declarations in reverse order to prioritize child styles
118

119
### Parsing Priority Logic
120

121
```typescript
122
// Example of nested span parsing with multiple background colors
123
// <span style="background-color: blue;"><span style="background-color: yellow;">text</span></span>
124
// Result: backgroundColor will be "yellow" (child takes priority)
125

126
// Example of multiple declarations in same element
127
// <span style="font-size: 14px; background-color: red; background-color: green;">text</span>
128
// Result: backgroundColor will be "green" (last declaration wins)
129
```
130

131
### Rendering Output
132

133
- **CSS Format**: Renders as `style="background-color: {value}"` attribute
134
- **Clean Output**: Only adds background-color attribute when a value is present
135
- **Format Preservation**: Maintains original color format when possible
136

137
## Type System Integration
138

139
### Module Augmentation
140

141
The BackgroundColor extension augments TipTap's type system:
142

143
```typescript
144
// Extends core Commands interface
145
declare module '@tiptap/core' {
146
  interface Commands<ReturnType> {
147
    backgroundColor: {
148
      setBackgroundColor: (backgroundColor: string) => ReturnType;
149
      unsetBackgroundColor: () => ReturnType;
150
    }
151
  }
152
}
153

154
// Extends TextStyleAttributes interface  
155
declare module '@tiptap/extension-text-style' {
156
  interface TextStyleAttributes {
157
    backgroundColor?: string | null;
158
  }
159
}
160
```
161

162
## Configuration Examples
163

164
### Basic Configuration
165

166
```typescript
167
import { BackgroundColor } from "@tiptap/extension-text-style/background-color";
168

169
const backgroundColorExtension = BackgroundColor.configure({
170
  types: ['textStyle']
171
});
172
```
173

174
### Extended Node Type Support
175

176
```typescript
177
const backgroundColorExtension = BackgroundColor.configure({
178
  types: ['textStyle', 'heading', 'paragraph']
179
});
180
```
181

182
This allows background colors to be applied directly to headings and paragraphs in addition to inline text styling.
183

184
## Advanced Parsing Details
185

186
### Style Attribute Processing
187

188
The extension processes HTML `style` attributes with special logic:
189

190
1. **Split Declarations**: Splits style attribute by semicolons
191
2. **Reverse Search**: Searches declarations from last to first for background-color
192
3. **Property Extraction**: Extracts property name and value, handling colons in values
193
4. **Fallback**: Falls back to `element.style.backgroundColor` if style attribute parsing fails
194

195
This approach ensures compatibility with content from various rich text editors and maintains styling priority correctly.