---
title: "Improve Dropdown"
description: "Add AI-powered text improvement capabilities to your Tiptap editor. More in the documentation!"
canonical_url: "https://tiptap.dev/docs/ui-components/components/improve-dropdown"
---

# Improve Dropdown

Add AI-powered text improvement capabilities to your Tiptap editor. More in the documentation!

A fully accessible AI-powered dropdown menu for Tiptap editors. Enhance your text with intelligent suggestions including grammar fixes, tone adjustments, translations, and content modifications with keyboard shortcuts and mobile support.

> **Interactive demo:** [improve dropdown](https://template.tiptap.dev/preview/tiptap-ui/improve-dropdown)

## Installation

Add the component via the Tiptap CLI:

```bash
npx @tiptap/cli@latest add improve-dropdown
```

## Components

### `<ImproveDropdown />`

A prebuilt React component that provides AI-powered text improvement options in a dropdown interface.

#### Usage

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

// --- Tiptap Core Extensions ---
import { StarterKit } from '@tiptap/starter-kit'
import { Ai } from '@tiptap-pro/extension-ai'
import { Selection } from '@tiptap/extensions'

// --- Tiptap UI ---
import { ImproveDropdown } from '@/components/tiptap-ui/improve-dropdown'
import { AiMenu } from '@/components/tiptap-ui/ai-menu'
import { TIPTAP_AI_APP_ID } from '@/lib/tiptap-collab-utils'
import { UiState } from '@/components/tiptap-extension/ui-state-extension'
import { AiProvider, useAi } from '@/components/contexts/ai-context'

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

// --- Tiptap Node ---
import '@/components/tiptap-node/blockquote-node/blockquote-node.scss'
import '@/components/tiptap-node/code-block-node/code-block-node.scss'
import '@/components/tiptap-node/horizontal-rule-node/horizontal-rule-node.scss'
import '@/components/tiptap-node/heading-node/heading-node.scss'
import '@/components/tiptap-node/list-node/list-node.scss'
import '@/components/tiptap-node/paragraph-node/paragraph-node.scss'

export const ImproveDropdownExample = () => {
  return (
    <AiProvider>
      <AiEditorWrapper />
    </AiProvider>
  )
}

const AiEditorWrapper = () => {
  const { aiToken } = useAi()

  if (!aiToken) {
    return <div className="tiptap-editor-wrapper">Loading AI...</div>
  }

  return <AiEditor aiToken={aiToken} />
}

const AiEditor = ({ aiToken }: { aiToken: string }) => {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit,
      Selection,
      UiState,
      Ai.configure({
        appId: TIPTAP_AI_APP_ID,
        token: aiToken,
        autocompletion: false,
        showDecorations: true,
        hideDecorationsOnStreamEnd: false,
        onLoading: (context) => {
          context.editor.commands.aiGenerationSetIsLoading(true)
          context.editor.commands.aiGenerationHasMessage(false)
        },
        onChunk: (context) => {
          context.editor.commands.aiGenerationSetIsLoading(true)
          context.editor.commands.aiGenerationHasMessage(true)
        },
        onSuccess: (context) => {
          const hasMessage = !!context.response
          context.editor.commands.aiGenerationSetIsLoading(false)
          context.editor.commands.aiGenerationHasMessage(hasMessage)
        },
      }),
    ],
    content: `
        <p>Select this text to see the improve dropdown menu with AI-powered text enhancement options.</p>
        <p>You can try improving this sentence: "This is a sample sentence that could use some improvement and maybe it's a bit too long and could be simplified or extended depending on what you need."</p>
        <p>Or this one: "ai can help with grammar and spelling mistakes in your writing"</p>
        `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <div className="controls-bar">
        <div className="control-item">
          <ButtonGroup orientation="horizontal">
            <ImproveDropdown
              textOptions={{
                stream: true,
                format: 'rich-text',
              }}
              hideWhenUnavailable={false}
            />
          </ButtonGroup>
        </div>
      </div>

      <EditorContent editor={editor} role="presentation" className="control-showcase">
        <AiMenu />
      </EditorContent>
    </EditorContext.Provider>
  )
}
```

#### Props

| Name                  | Type             | Default                                 | Description                                           |
| --------------------- | ---------------- | --------------------------------------- | ----------------------------------------------------- |
| `editor`              | `Editor \| null` | `undefined`                             | The Tiptap editor instance                            |
| `textOptions`         | `TextOptions`    | `{ stream: true, format: "rich-text" }` | Configuration options for AI text processing          |
| `hideWhenUnavailable` | `boolean`        | `false`                                 | Hides the dropdown when AI features are not available |
| `onImproved`          | `() => void`     | `undefined`                             | Callback fired after a successful text improvement    |
| `portal`              | `boolean`        | `false`                                 | Whether to render the dropdown menu in a portal       |

## Hooks

### `useImproveDropdown()`

A custom hook to build your own improve dropdown with full control over rendering and behavior.

#### Usage

```tsx
function MyImproveDropdown() {
  const {
    isVisible,
    isDisabled,
    isOpen,
    handleOpenChange,
    executeAICommand,
    adjustTone,
    translate,
    Icon,
  } = useImproveDropdown({
    editor: myEditor,
    hideWhenUnavailable: true,
    onImproved: () => console.log('Text improved!'),
  })

  if (!isVisible) return null

  return (
    <DropdownMenu open={isOpen} onOpenChange={handleOpenChange}>
      <DropdownMenuTrigger asChild>
        <button disabled={isDisabled} aria-label="Improve text">
          <Icon />
          Improve
        </button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem onClick={() => executeAICommand('fixSpellingAndGrammar')}>
          Fix spelling & grammar
        </DropdownMenuItem>
        <DropdownMenuItem onClick={() => executeAICommand('extend')}>Extend text</DropdownMenuItem>
        <DropdownMenuItem onClick={() => adjustTone('professional')}>
          Make professional
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

#### Props

| Name                  | Type             | Default     | Description                                         |
| --------------------- | ---------------- | ----------- | --------------------------------------------------- |
| `editor`              | `Editor \| null` | `undefined` | The Tiptap editor instance                          |
| `hideWhenUnavailable` | `boolean`        | `false`     | Hides the dropdown if AI features are not available |
| `onImproved`          | `() => void`     | `undefined` | Callback fired after a successful text improvement  |

#### Return Values

| Name               | Type                         | Description                                  |
| ------------------ | ---------------------------- | -------------------------------------------- |
| `isVisible`        | `boolean`                    | Whether the dropdown should be rendered      |
| `isDisabled`       | `boolean`                    | Whether AI commands are currently disabled   |
| `isOpen`           | `boolean`                    | Whether the dropdown is currently open       |
| `handleOpenChange` | `(open: boolean) => void`    | Function to handle dropdown open/close state |
| `executeAICommand` | `(command: string) => void`  | Function to execute AI improvement commands  |
| `adjustTone`       | `(tone: string) => void`     | Function to adjust text tone                 |
| `translate`        | `(language: string) => void` | Function to translate text                   |
| `Icon`             | `React.FC`                   | Icon component for the improve dropdown      |

## AI Features

The improve dropdown provides various AI-powered text enhancement options:

### Text Enhancement

- **Fix spelling & grammar** - Automatically corrects spelling mistakes and grammar errors
- **Extend text** - Expands content with additional relevant information
- **Reduce text** - Shortens content while preserving meaning
- **Simplify text** - Makes complex text more readable and accessible
- **Emojify** - Adds relevant emojis to make text more engaging

### Content Operations

- **Complete sentence** - Intelligently completes incomplete sentences
- **Summarize** - Creates concise summaries of longer text

### Advanced Options

- **Adjust tone** - Modifies text tone (professional, casual, friendly, etc.)
- **Translate** - Translates text to different languages

## Utilities

### `canUseAi(editor)`

Checks if AI features can be used with the current selection in the editor.

```tsx
import { canUseAi } from '@/components/tiptap-ui/improve-dropdown'

const aiAvailable = canUseAi(editor)
if (aiAvailable) {
  // Show AI options
}
```

### `shouldShowImproveDropdown(params)`

Determines whether the improve dropdown should be displayed based on editor state and configuration.

```tsx
import { shouldShowImproveDropdown } from '@/components/tiptap-ui/improve-dropdown'

const shouldShow = shouldShowImproveDropdown({
  editor,
  hideWhenUnavailable: true,
})
```

### `executeAICommand(editor, command, textOptions?)`

Programmatically executes an AI improvement command on the current selection.

```tsx
import { executeAICommand } from '@/components/tiptap-ui/improve-dropdown'

const success = executeAICommand(editor, 'fixSpellingAndGrammar')
if (success) {
  console.log('Grammar fixed successfully!')
}
```

## Requirements

### Dependencies

- `@tiptap/react` - Core Tiptap React integration
- `@tiptap-pro/extension-ai` - AI extension for text improvements
- `react-hotkeys-hook` - Keyboard shortcut management

### Referenced Components

- `use-tiptap-editor` (hook)
- `dropdown-menu` (primitive)
- `button` (primitive)
- `card` (primitive)
- `separator` (primitive)
- `ai-sparkles-icon` (icon)
- `check-ai-icon` (icon)
- `text-extend-icon` (icon)
- `text-reduce-icon` (icon)
- `simplify-2-icon` (icon)
- `smile-ai-icon` (icon)
- `complete-sentence-icon` (icon)
- `summarize-text-icon` (icon)
- `languages-icon` (icon)
- `mic-ai-icon` (icon)

### AI Configuration

The component requires proper AI extension setup in your Tiptap editor configuration for full functionalit