Color highlight popover

Available for free

A fully accessible highlight color selection popover for Tiptap editors. Apply background highlights with a curated color palette, remove highlights, and provide an intuitive interface for text highlighting with keyboard shortcuts and mobile support.

Installation

Add the component via the Tiptap CLI:

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

Components

`<ColorHighlightPopover />`

A prebuilt React component that provides highlight color selection in a compact popover interface.

Usage

import { EditorContent, EditorContext, useEditor } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'
import { Highlight } from '@tiptap/extension-highlight'
import { ColorHighlightPopover } from '@/components/tiptap-ui/color-highlight-popover'

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: `
        <p style="text-align: left">
            <mark data-color="var(--tt-color-highlight-purple)" style="background-color: var(--tt-color-highlight-purple); color: inherit">
                <span class="selection">Highlight text</span>
            </mark>
            <span class="selection"> </span>
            <mark data-color="var(--tt-color-highlight-red)" style="background-color: var(--tt-color-highlight-red); color: inherit">
                <span class="selection">in</span>
            </mark>
            <span class="selection"> </span>
            <mark data-color="var(--tt-color-highlight-green)" style="background-color: var(--tt-color-highlight-green); color: inherit">
                <span class="selection">different</span>
            </mark>
            <span class="selection"> </span>
            <mark data-color="var(--tt-color-highlight-blue)" style="background-color: var(--tt-color-highlight-blue); color: inherit">
                <span class="selection">colors</span>
            </mark>
            <span class="selection"> to draw attention to key points.</span>
        </p>
        `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <ColorHighlightPopover
        editor={editor}
        hideWhenUnavailable={true}
        onApplied={({ color, label }) => console.log(`Applied highlight: ${label} (${color})`)}
      />

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

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`colors`	`HighlightColor[]`	Default palette	Custom highlight colors to display
`hideWhenUnavailable`	`boolean`	`false`	Hides the popover when highlighting is not available
`onApplied`	`HighlightHandler`	`undefined`	Callback fired when a highlight is applied or removed

`<ColorHighlightPopoverContent />`

The content component that displays the color palette and remove option. Can be used independently for custom popover implementations.

Usage

<PopoverContent>
  <ColorHighlightPopoverContent editor={editor} colors={customColors} />
</PopoverContent>

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`colors`	`HighlightColor[]`	Default palette	Custom highlight colors to display

Hooks

`useColorHighlight()`

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

Usage

function MyHighlightButton() {
  const {
    isVisible,
    isActive,
    canColorHighlight,
    handleColorHighlight,
    handleRemoveHighlight,
    label,
    shortcutKeys,
    Icon,
  } = useColorHighlight({
    editor: myEditor,
    highlightColor: 'var(--tt-color-highlight-yellow)',
    label: 'Yellow Highlight',
    hideWhenUnavailable: true,
    onApplied: ({ color, label }) => {
      console.log(`Highlight applied: ${label} (${color})`)
    },
  })

  if (!isVisible) return null

  return (
    <button
      onClick={handleColorHighlight}
      disabled={!canColorHighlight}
      aria-label={label}
      aria-pressed={isActive}
    >
      <Icon />
      {label}
      <kbd>{shortcutKeys}</kbd>
    </button>
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`highlightColor`	`string`	`undefined`	CSS color value for the highlight
`label`	`string`	`undefined`	Accessible label for the highlight
`hideWhenUnavailable`	`boolean`	`false`	Hide when highlighting is not available
`onApplied`	`HighlightHandler`	`undefined`	Callback for highlight changes

Return Values

Name	Type	Description
`isVisible`	`boolean`	Whether the button should be rendered
`isActive`	`boolean`	If the highlight is currently active
`canColorHighlight`	`boolean`	If highlighting is currently allowed
`handleColorHighlight`	`() => boolean`	Function to apply/toggle the highlight
`handleRemoveHighlight`	`() => boolean`	Function to remove any highlight
`label`	`string`	Accessible label text for the button
`shortcutKeys`	`string`	Keyboard shortcut (Cmd/Ctrl + Shift + H)
`Icon`	`React.FC`	Icon component for the highlight button

Utility Functions

`canColorHighlight(editor)`

Checks if highlighting is available in the current editor state.

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

const canHighlight = canColorHighlight(editor)
if (canHighlight) {
  // Show highlight options
}

`removeHighlight(editor)`

Programmatically removes any highlight from the current selection.

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

const success = removeHighlight(editor)
if (success) {
  console.log('Highlight removed!')
}

Keyboard Shortcuts

The highlight popover supports the following keyboard shortcut:

Cmd/Ctrl + Shift + H: Toggle highlight (when a specific color is configured)

// Shortcut works automatically with useColorHighlight hook
const { shortcutKeys } = useColorHighlight({
  editor,
  highlightColor: 'var(--tt-color-highlight-yellow)',
})

console.log(shortcutKeys) // "mod+shift+h"

Requirements

Dependencies

@tiptap/react - Core Tiptap React integration
@tiptap/extension-highlight - Highlight extension for text highlighting

Referenced Components

use-tiptap-editor (hook)
use-menu-navigation (hook)
use-mobile (hook)
button (primitive)
popover (primitive)
card (primitive)
separator (primitive)
highlighter-icon (icon)
ban-icon (icon)
color-highlight-button (component)
tiptap-utils (lib)