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

Color Text Popover | Tiptap UI Components

Highlight text in different colors to draw attention to key points.

## 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)
```

## Utility Functions

### `getColorByValue(value, colorArray)`

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

```
import { getColorByValue, TEXT_COLORS } from '@/components/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 '@/components/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)