Color Highlight Button

Available for free

A fully accessible and customizable color highlight button for Tiptap editors. Apply background colors to selected text using keyboard shortcuts or UI, with support for dynamic color sets, custom rendering, and accessibility.

Installation

Add the component via the Tiptap CLI:

npx @tiptap/cli@latest add color-highlight-button

Components

`<ColorHighlightButton />`

A ready-to-use React button for applying color highlights to selected text in a Tiptap editor.

Usage

import { EditorContent, EditorContext, useEditor } from '@tiptap/react'

// --- Tiptap Core Extensions ---
import { StarterKit } from '@tiptap/starter-kit'
import { Highlight } from '@tiptap/extension-highlight'

// --- Tiptap UI ---
import { ColorHighlightButton } from '@/components/tiptap-ui/color-highlight-button'

// --- UI Primitive ---
import { ButtonGroup } from '@/components/tiptap-ui-primitive/button'

// --- Node Styles ---
import '@/components/tiptap-node/code-block-node/code-block-node.scss'
import '@/components/tiptap-node/paragraph-node/paragraph-node.scss'

export default function MyEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [StarterKit, Highlight.configure({ multicolor: true })],
    content: `
      <h2>Color Highlight Button Demo</h2>
      <p>Welcome to the color highlight button! This demo showcases functionality.</p>
      <h3>How to Use:</h3>
      <p>1. <strong>Select any text</strong> you want to highlight</p>
      <p>2. <strong>Click a color button</strong> to apply that <mark data-color="oklch(88.5% 0.062 18.334)" style="background-color: oklch(88.5% 0.062 18.334); color: inherit">highlight</mark></p>
    `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <ButtonGroup orientation="horizontal">
        <ColorHighlightButton tooltip="Red" highlightColor="oklch(88.5% 0.062 18.334)" />
        <ColorHighlightButton
          editor={editor}
          tooltip="Orange"
          highlightColor="oklch(90.1% 0.076 70.697)"
          text="Highlight"
          hideWhenUnavailable={true}
          showShortcut={true}
          onApplied={({ color, label }) => console.log(`Applied ${label} highlight: ${color}`)}
        />
      </ButtonGroup>

      <EditorContent editor={editor} role="presentation" />
    </EditorContext.Provider>
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`highlightColor`	`string`	`required`	The highlight color to apply (CSS color value)
`text`	`string`	`undefined`	Optional text label for the button
`hideWhenUnavailable`	`boolean`	`false`	Hides the button when highlight is not applicable
`onApplied`	`({ color, label }) => void`	`undefined`	Callback fired after applying a highlight
`showShortcut`	`boolean`	`false`	Shows a keyboard shortcut badge (if available)

Hooks

`useColorHighlight(config)`

A powerful hook to build your own custom color highlight button with full control over behavior and rendering.

Usage

import { useColorHighlight } from '@/components/tiptap-ui/color-highlight-button'
import { Badge } from '@/components/tiptap-ui-primitive/badge'
import { parseShortcutKeys } from '@/lib/tiptap-utils'

function MyColorHighlightButton() {
  const { isVisible, isActive, canColorHighlight, handleColorHighlight, label, shortcutKeys } =
    useColorHighlight({
      editor: myEditor,
      highlightColor: 'var(--tt-color-highlight-blue)',
      label: 'Blue Highlight',
      hideWhenUnavailable: true,
      onApplied: ({ color, label }) => console.log(`Applied: ${label}`),
    })

  if (!isVisible) return null

  return (
    <button
      onClick={handleColorHighlight}
      disabled={!canColorHighlight}
      aria-label={label}
      aria-pressed={isActive}
      style={{ backgroundColor: isActive ? highlightColor : 'transparent' }}
    >
      {label}
      {shortcutKeys && <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>}
    </button>
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`highlightColor`	`string`	`required`	The highlight color to apply
`label`	`string`	`optional`	Accessible label for the button
`hideWhenUnavailable`	`boolean`	`false`	Hides the button if highlight cannot be applied
`mode`	`"mark" \| "node"`	`"mark"`	Highlighting mode (mark or node background)
`onApplied`	`({ color, label, mode }) => void`	`undefined`	Callback fired after applying highlight

Return Values

Name	Type	Description
`isVisible`	`boolean`	Whether the button should be rendered
`isActive`	`boolean`	If the highlight is currently active
`canColorHighlight`	`boolean`	If the highlight can be applied
`handleColorHighlight`	`() => boolean`	Function to apply the color highlight
`handleRemoveHighlight`	`() => boolean`	Function to remove the highlight
`label`	`string`	Accessible label text for the button
`shortcutKeys`	`string`	Keyboard shortcut (Cmd/Ctrl + Shift + H)
`Icon`	`React.FC`	Icon component used (HighlighterIcon)
`mode`	`"mark" \| "node"`	The highlighting mode being used

Utilities

`canColorHighlight(editor, mode?)`

Checks if color highlight can be applied in the current editor state.

Parameters

Parameter	Type	Default	Description
`editor`	`Editor \| null`	Required	The Tiptap editor instance
`mode`	`"mark" \| "node"`	`"mark"`	Highlighting mode (mark or node background)

Returns

boolean - Whether highlight can be applied

Usage

import { canColorHighlight } from '@/components/tiptap-ui/color-highlight-button'

const canApply = canColorHighlight(editor)
const canApplyNode = canColorHighlight(editor, 'node')

`isColorHighlightActive(editor, highlightColor?, mode?)`

Checks if a color highlight is currently active in the selection.

Parameters

Parameter	Type	Default	Description
`editor`	`Editor \| null`	Required	The Tiptap editor instance
`highlightColor`	`string`	`undefined`	The specific color to check for
`mode`	`"mark" \| "node"`	`"mark"`	Highlighting mode (mark or node background)

Returns

boolean - Whether the highlight is active

Usage

import { isColorHighlightActive } from '@/components/tiptap-ui/color-highlight-button'

const isActive = isColorHighlightActive(editor) // Any highlight active
const isYellowActive = isColorHighlightActive(editor, 'var(--tt-color-highlight-yellow)') // Specific color active
const isNodeHighlight = isColorHighlightActive(editor, 'var(--tt-color-highlight-blue)', 'node')

`removeHighlight(editor, mode?)`

Removes the current highlight from the selection.

Parameters

Parameter	Type	Default	Description
`editor`	`Editor \| null`	Required	The Tiptap editor instance
`mode`	`"mark" \| "node"`	`"mark"`	Highlighting mode (mark or node background)

Returns

boolean - Whether the highlight was successfully removed

Usage

import { removeHighlight } from '@/components/tiptap-ui/color-highlight-button'

const success = removeHighlight(editor)
const successNode = removeHighlight(editor, 'node')

`pickHighlightColorsByValue(values)`

Filters the default highlight colors by their values.

Parameters

Parameter	Type	Description
`values`	`string[]`	Array of color values to filter by

Returns

HighlightColor[] - Array of matching highlight color objects

Usage

import { pickHighlightColorsByValue } from '@/components/tiptap-ui/color-highlight-button'

const colors = pickHighlightColorsByValue([
  'var(--tt-color-highlight-yellow)',
  'var(--tt-color-highlight-blue)',
])
// Returns the full color objects with label, value, and border properties

Keyboard Shortcuts

The color highlight button supports the following keyboard shortcut:

Cmd/Ctrl + Shift + H: Apply color highlight

This shortcut is automatically registered when using the ColorHighlightButton or useColorHighlight() hook, and applies the configured highlight color to the current selection.

Requirements

Dependencies

@tiptap/react - Core Tiptap React integration
@tiptap/extension-highlight - Highlight extension for text highlighting
react-hotkeys-hook - Keyboard shortcut management

Referenced Components

use-tiptap-editor (hook)
button (primitive)
badge (primitive)
tiptap-utils (lib)
highlighter-icon (icon)

PreviouslyCode block button

Next upColor highlight popover