tessl/npm-tiptap--extension-text-style

Text styling extension for TipTap rich text editor providing color, background, font family, font size, and line height capabilities.

—

Pending

Overview

Eval results

Files

Background Color Styling

Name: tessl/npm-tiptap--extension-text-style
Author: tessl

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

Capabilities

BackgroundColor Extension

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

/**
 * Extension for setting background color on specified node types
 * Extends textStyle mark with backgroundColor attribute
 */
const BackgroundColor: Extension<BackgroundColorOptions>;

interface BackgroundColorOptions {
  /** 
   * Node types where background color can be applied
   * @default ['textStyle']
   * @example ['heading', 'paragraph', 'textStyle']
   */
  types: string[];
}

Usage Example:

import { Editor } from "@tiptap/core";
import { BackgroundColor } from "@tiptap/extension-text-style/background-color";
import { TextStyle } from "@tiptap/extension-text-style/text-style";

const editor = new Editor({
  extensions: [
    TextStyle, // Required dependency
    BackgroundColor.configure({
      types: ['textStyle', 'paragraph']
    })
  ]
});

Set Background Color Command

Apply a specific background color to the current text selection.

/**
 * Set the text background color
 * @param backgroundColor - CSS color value (hex, rgb, hsl, named colors, etc.)
 * @returns Command result indicating success/failure
 */
setBackgroundColor(backgroundColor: string): Command;

Usage Examples:

// Hex colors
editor.commands.setBackgroundColor("#ffff00");
editor.commands.setBackgroundColor("#f0f8ff");

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

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

// Named colors
editor.commands.setBackgroundColor("yellow");
editor.commands.setBackgroundColor("lightcyan");

// Chain with other styling commands
editor.chain()
  .setBackgroundColor("#ffffcc")
  .setColor("#333333")
  .run();

Unset Background Color Command

Remove background color styling from the current text selection.

/**
 * Unset the text background color, removing backgroundColor attribute and cleaning up empty textStyle marks
 * @returns Command result indicating success/failure
 */
unsetBackgroundColor(): Command;

Usage Example:

// Remove background color and clean up empty styling
editor.commands.unsetBackgroundColor();

// Chain removal with other operations
editor.chain()
  .unsetBackgroundColor()
  .setColor("#000000")
  .run();

HTML Processing

Advanced Background Color Parsing

The BackgroundColor extension includes sophisticated HTML parsing that:

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

Parsing Priority Logic

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

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

Rendering Output

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

Type System Integration

Module Augmentation

The BackgroundColor extension augments TipTap's type system:

// Extends core Commands interface
declare module '@tiptap/core' {
  interface Commands<ReturnType> {
    backgroundColor: {
      setBackgroundColor: (backgroundColor: string) => ReturnType;
      unsetBackgroundColor: () => ReturnType;
    }
  }
}

// Extends TextStyleAttributes interface  
declare module '@tiptap/extension-text-style' {
  interface TextStyleAttributes {
    backgroundColor?: string | null;
  }
}

Configuration Examples

Basic Configuration

import { BackgroundColor } from "@tiptap/extension-text-style/background-color";

const backgroundColorExtension = BackgroundColor.configure({
  types: ['textStyle']
});

Extended Node Type Support

const backgroundColorExtension = BackgroundColor.configure({
  types: ['textStyle', 'heading', 'paragraph']
});

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

Advanced Parsing Details

Style Attribute Processing

The extension processes HTML style attributes with special logic:

Split Declarations: Splits style attribute by semicolons
Reverse Search: Searches declarations from last to first for background-color
Property Extraction: Extracts property name and value, handling colons in values
Fallback: Falls back to element.style.backgroundColor if style attribute parsing fails

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

Install with Tessl CLI

npx tessl i tessl/npm-tiptap--extension-text-style

docs