Skip to main content
The Background Color extension adds support for customizing text background color with commands for adding and removing background color.

​
Installation

npm install @prosekit/extensions

​
Usage

Add the background color extension to your editor: 
import { defineBackgroundColor } from '@prosekit/extensions/background-color'
import { createEditor } from '@prosekit/core'

const editor = createEditor({
  extensions: [
    // ... other extensions
    defineBackgroundColor(),
  ],
})

​
API Reference

​
defineBackgroundColor()

Defines the backgroundColor mark and commands for adding and removing background color. Returns: BackgroundColorExtension

​
Commands

​
addBackgroundColor

Applies a background color to the current selection or at the cursor position. 
editor.commands.addBackgroundColor({ color: '#ffff00' })
Parameters:
  • attrs: BackgroundColorAttrs - Object with a color property
    • color: string - Any valid CSS color value (hex, rgb, rgba, color name, etc.)

​
removeBackgroundColor

Removes background color formatting from the current selection. 
editor.commands.removeBackgroundColor()

​
TypeScript Types

​
BackgroundColorAttrs

Attributes for the backgroundColor mark. 
interface BackgroundColorAttrs {
  color: string
}

​
HTML Output

Background color is rendered as <span> elements with both inline styles and data attributes: 
<span style="background-color: #ffff00;" data-background-color="#ffff00">Highlighted text</span>

​
Parsing

The extension recognizes elements with:
  • style="background-color: [value]" attribute
  • data-background-color="[value]" attribute (takes priority)
The extension uses data-background-color attribute to preserve exact color values, avoiding browser conversion of hex colors to rgba format.
Colors set to "inherit" are ignored during parsing.

​
Example: Color Picker Integration

Here’s an example of integrating a color picker for highlighting: 
import { defineBackgroundColor } from '@prosekit/extensions/background-color'
import { createEditor } from '@prosekit/core'

const editor = createEditor({
  extensions: [defineBackgroundColor()],
})

// Apply background color from a color picker
function handleHighlightColorChange(color: string) {
  editor.commands.addBackgroundColor({ color })
}

// Remove background color
function handleHighlightRemove() {
  editor.commands.removeBackgroundColor()
}

​
Supported Color Formats

The extension accepts any valid CSS color value:
  • Hex: #ffff00, #ff0
  • RGB: rgb(255, 255, 0)
  • RGBA: rgba(255, 255, 0, 0.5)
  • HSL: hsl(60, 100%, 50%)
  • Named colors: yellow, lightblue, etc.

​
Common Use Cases

​
Text Highlighting

// Yellow highlight
editor.commands.addBackgroundColor({ color: '#ffff00' })

// Green highlight
editor.commands.addBackgroundColor({ color: '#90EE90' })

// Pink highlight
editor.commands.addBackgroundColor({ color: '#FFB6C1' })

​
Combined with Text Color

import { defineTextColor } from '@prosekit/extensions/text-color'
import { defineBackgroundColor } from '@prosekit/extensions/background-color'

const editor = createEditor({
  extensions: [
    defineTextColor(),
    defineBackgroundColor(),
  ],
})

// Apply both text and background color
editor.commands.addTextColor({ color: '#ffffff' })
editor.commands.addBackgroundColor({ color: '#000000' })

​
Advanced Configuration

If you need more control, you can use the individual components: 
import { 
  defineBackgroundColorSpec,
  defineBackgroundColorCommands,
  addBackgroundColor,
  removeBackgroundColor
} from '@prosekit/extensions/background-color'

const editor = createEditor({
  extensions: [
    defineBackgroundColorSpec(),      // Just the mark definition
    defineBackgroundColorCommands(),  // Just the commands
  ],
})

// Use the command functions directly
addBackgroundColor({ color: '#e0e0e0' })(editor.state, editor.dispatch)