Color Text Popover

A fully accessible text color button for Tiptap editors. Apply foreground colors to selected text with keyboard shortcut support and flexible customization options.

Installation

Add the component via the Tiptap CLI:

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

Components

`<ColorTextPopover />`

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

Usage

export default function MyEditor() {
  return (
    <ColorTextPopover
      editor={editor}
      hideWhenUnavailable={true}
      onColorChanged={({ type, label, value }) =>
        console.log(`Applied ${type} color: ${label} (${value})`)
      }
    />
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`hideWhenUnavailable`	`boolean`	`false`	Hides the popover when color styling is not available
`onColorChanged`	`ColorChangeHandler`	`undefined`	Callback fired when a color is applied

Hooks

`useColorTextPopover()`

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

Usage

function MyColorPopover() {
  const {
    isVisible,
    canToggle,
    activeTextStyle,
    activeHighlight,
    handleColorChanged,
    label,
    Icon,
  } = useColorTextPopover({
    editor: myEditor,
    hideWhenUnavailable: true,
    onColorChanged: ({ type, label, value }) => {
      console.log(`Color changed: ${type} - ${label} (${value})`)
    },
  })

  if (!isVisible) return null

  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button disabled={!canToggle} aria-label={label}>
          <Icon
            style={{
              color: activeTextStyle.color,
              backgroundColor: activeHighlight.color,
            }}
          />
        </Button>
      </PopoverTrigger>
      <PopoverContent>
        <TextStyleColorPanel onColorChanged={handleColorChanged} />
      </PopoverContent>
    </Popover>
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`hideWhenUnavailable`	`boolean`	`false`	Hide when color features are not available
`onColorChanged`	`ColorChangeHandler`	`undefined`	Callback for color changes

Return Values

Name	Type	Description
`isVisible`	`boolean`	Whether the popover should be rendered
`canToggle`	`boolean`	If color changes are currently allowed
`activeTextStyle`	`object`	Current text style attributes (includes color)
`activeHighlight`	`object`	Current highlight attributes (includes color)
`handleColorChanged`	`ColorChangeHandler`	Function to handle color selection
`label`	`string`	Accessible label text for the trigger button
`Icon`	`React.FC`	Icon component for the color popover button

Color Management

Recent Colors

The popover automatically tracks and displays recently used colors using the useRecentColors hook:

const { recentColors, addRecentColor, isInitialized } = useRecentColors(3)

// Recent colors are automatically stored in localStorage

Utility Functions

`getColorByValue(value, colorArray)`

Finds a color object by its value from a color array.

import { getColorByValue, TEXT_COLORS } from '@/registry/tiptap-ui/color-text-popover'

const blueColor = getColorByValue('var(--tt-color-text-blue)', TEXT_COLORS)
// Returns: { label: "Blue text", value: "var(--tt-color-text-blue)", ... }

`shouldShowColorTextPopover(params)`

Determines if the color popover should be visible based on editor state.

import { shouldShowColorTextPopover } from '@/registry/tiptap-ui/color-text-popover'

const shouldShow = shouldShowColorTextPopover({
  editor: myEditor,
  hideWhenUnavailable: true,
})

Requirements

Dependencies

@tiptap/react - Core Tiptap React integration
@tiptap/extension-text-style - Text style extension for color support
@tiptap/extension-highlight - Highlight extension for text highlighting

Referenced Components

use-tiptap-editor (hook)
use-menu-navigation (hook)
button (primitive)
popover (primitive)
card (primitive)
chevron-down-icon (icon)
text-color-small-icon (icon)
color-text-button (component)
color-highlight-button (component)
tiptap-utils (lib)