# Integrating CKEditor AI with your application

To run CKEditor AI in your editor, add the AI plugins and provide the required configuration. This guide covers the installation, configuration, and customization options.

<a id="installation">

## Installation

After [installing the editor](../../getting-started/installation/cloud/quick-start.md), add the feature to your plugin list and provide [essential configuration](#sample-implementation):

**NPM**

```js
import { ClassicEditor } from 'ckeditor5';
import { AIChat, AIQuickActions, AIActions, AIReviewMode, AITranslate, AIBalloon, AIEditorIntegration, AIChatShortcuts, TrackChanges } from 'ckeditor5-premium-features';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',

		plugins: [
			// AI plugins responsible for the core functionality.
			AIChat, AIQuickActions, AIReviewMode, AITranslate, AIEditorIntegration, AIChatShortcuts,

			// Recommended TrackChanges dependency. Follow the guide to learn more.
			TrackChanges,

			/* ... */
		],

		// AI feature configuration.
		ai: {
			// Mandatory UI configuration.
			container: {
				/* ... */
			},

			/* ... */
		}

		/* Other configurations. Follow the guide to learn more. */
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor } = CKEDITOR;
const { AIChat, AIQuickActions, AIActions, AIReviewMode, AITranslate, AIBalloon, AIEditorIntegration, AIChatShortcuts, TrackChanges } = CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',

		plugins: [
			// AI plugins responsible for the core functionality.
			AIChat, AIQuickActions, AIReviewMode, AITranslate, AIEditorIntegration, AIChatShortcuts,

			// Recommended TrackChanges dependency. Follow the guide to learn more.
			TrackChanges,

			/* ... */
		],

		// AI feature configuration.
		ai: {
			// Mandatory UI configuration.
			container: {
				/* ... */
			},

			/* ... */
		}

		/* Other configurations. Follow the guide to learn more. */
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

> **Note**
>
> You must configure a user interface type for the AI features to work. Learn more about the available options in the [UI placement](#ui-types-and-positioning) section or use the [sample implementation](#sample-implementation) as a reference.

> **Note**
>
> Using AI features with the `TrackChanges` plugin requires the `Users` plugin integration. Learn more about the [Track Changes plugin integration](#track-changes-dependency) or refer to the [sample implementation](#sample-implementation) for more details.

> **Note**
>
> Read more about [installing plugins](../../getting-started/setup/configuration.md) and [toolbar configuration](../../getting-started/setup/toolbar.md).

<a id="enabling-individual-features">

### Enabling individual features

Each AI feature is a standalone plugin that you can include or exclude from the `plugins` array depending on your needs. For example, to use only AI Review and AI Translate without Chat or Quick Actions:

```js
import { ClassicEditor } from 'ckeditor5';
import { AIReviewMode, AITranslate, AIEditorIntegration, TrackChanges } from 'ckeditor5-premium-features';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',

		plugins: [
			AIReviewMode, AITranslate, AIEditorIntegration, TrackChanges,
			/* ... */
		],

		ai: {
			container: {
				/* ... */
			}
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

The following table lists the plugins responsible for each feature:

| Feature           | Plugin            | Description                                   |
| ----------------- | ----------------- | --------------------------------------------- |
| AI Chat           | `AIChat`          | Conversational AI assistant                   |
| AI Chat Shortcuts | `AIChatShortcuts` | Predefined shortcuts displayed in the AI Chat |
| AI Quick Actions  | `AIQuickActions`  | One-click AI-powered content transformations  |
| AI Review         | `AIReviewMode`    | AI-powered quality assurance checks           |
| AI Translate      | `AITranslate`     | AI-powered document translation               |

> **Note**
>
> The [`AIEditorIntegration`](../../api/module_ai_aieditorintegration_aieditorintegration-AIEditorIntegration.md) plugin is required for all setups as it provides the core editor integration, including the `'toggleAi'` toolbar button.

<a id="sample-implementation">

## Sample implementation

An example CKEditor AI configuration is presented below. You can learn more about specific configurations such as [UI types and positioning](#ui-types-and-positioning) or [Track Changes dependency](#track-changes-dependency) in the later sections of this guide.

To learn more about toolbar configuration, refer to the [toolbar configuration](../../getting-started/setup/toolbar.md) guide.

```js
// Simplified integration of the Users plugin needed for TrackChanges integration.
class UsersIntegration extends Plugin {
	static get requires() {
		return [ 'Users' ];
	}

	init() {
		const users = this.editor.plugins.get( 'Users' );

		// Just add a minimal dummy user
		users.addUser( { id: 'user-1', name: 'John Doe' } );
		users.defineMe( 'user-1' );
	}
}

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',

		plugins: [ AIChat, AIQuickActions, AIReviewMode, AITranslate, AIEditorIntegration, AIChatShortcuts, TrackChanges, UsersIntegration, /* ... */ ],

		// Extend the main editor toolbar configuration with additional buttons:
		// - 'aiQuickActions': opens the AI Quick Actions menu,
		// - 'ask-ai': moves the user focus to the AI Chat,
		// - 'improve-writing': executes the "Improve Writing" quick action.
		//
		// You can add more AI Quick actions to the toolbar configuration if needed.
		toolbar: [ 'aiQuickActions', 'ask-ai', 'improve-writing', /* ... */ ],

		// You can use the same AI feature buttons in the balloon toolbar configuration for contextual convenience.
		balloonToolbar: {
			items: [
				/* ... */

				'aiQuickActions', 'ask-ai', 'improve-writing', /* ... */
			]
		},

		// Configure the document identifier for AI chat history and context preservation.
		// This should be a unique identifier for the document/article being edited.
		collaboration: {
			channelId: 'channelId' // Replace with your actual document ID
		},

		// Main configuration of AI feature.
		ai: {
			// ⚠️ Mandatory UI configuration.
			// Display the AI user interface in a dedicated DOM element. The interface can be also displayed
			// in an overlay or in a custom way, learn more in the next chapters of this guide.
			container: {
				type: 'sidebar',
				element: document.querySelector( '.ai-sidebar' ),

				// (Optional) Whether the AI interface should be visible when the editor is created.
				visibleByDefault: false
			},

			// (Optional) Configure the AI Chat feature by configuring available context resources.
			chat: {
				// (Optional) Configure AI Chat Shortcuts that appear at the start of a new conversation.
				shortcuts: [
					{
						id: 'continue-writing',
						type: 'chat',
						label: 'Continue writing',
						prompt: 'Continue writing this document. Match the existing tone, vocabulary level, and formatting. ' +
							'Do not repeat or summarize earlier sections. Ensure logical flow and progression of ideas. ' +
							'Add approximately 3 paragraphs.'
					}
				],

				context: {
					// Configuration of the built-in context options.
					document: {
						enabled: true
					},
					urls: {
						enabled: false
					},
					files: {
						enabled: true
					},

					// (Optional) Additional sources for the AI Chat context.
					sources: [
						// Definition of the custom context provider.
						{
							// The unique identifier of the provider.
							id: 'my-docs',

							// The human-readable name of the provider.
							label: 'My Documents',

							// The async callback to retrieve the list of available resources.
							// Usually involves fetching data from a database or an external API,
							// but here we use a simple array of resources for demonstration purposes.
							getResources: async ( query ) => [
								// Texts in various formats
								{
									id: 'text1',
									type: 'text',
									label: 'Internal note in plain text format',
									data: {
										content: 'Lorem ipsum dolor sit amet...',
										type: 'text'
									}
								},
								{
									id: 'text2',
									type: 'text',
									label: 'Internal note in Markdown format',
									data: {
										content: '## Markdown note\n\n**Lorem ipsum** dolor sit amet...',
										type: 'markdown'
									}
								},
								{
									id: 'text3',
									type: 'text',
									label: 'Internal note in HTML format',
									data: {
										content: '<h2>HTML note</h2><p>Lorem ipsum dolor sit amet...</p>',
										type: 'html'
									}
								},
								{
									id: 'text4',
									type: 'text',
									label: 'Internal note (fetched on demand)',

									// Note: Since the `data` property is not provided, the content will be retrieved using the `getData()` callback (see below).
									// This will prevent fetching large content along with the list of resources.
								},

								// URLs to resources in different formats
								{
									id: 'url1',
									type: 'web-resource',
									label: 'Blog post in Markdown',
									data: 'https://example.com/blog-post.md'
								},
								{
									id: 'url2',
									type: 'web-resource',
									label: 'Company brochure in PDF',
									data: 'https://example.com/brochure.pdf'
								},
								{
									id: 'url3',
									type: 'web-resource',
									label: 'Company website in HTML',
									data: 'https://example.com/index.html'
								},
								{
									id: 'url4',
									type: 'web-resource',
									label: 'Terms of service in plain text',
									data: 'https://example.com/terms-of-service.txt'
								},

								// ...
							],

							// The optional callback to retrieve the content of resources without the `data` property provided by the `getResources()` callback.
							// When the user picks a specific resource,  the content will be fetched on demand (from database or external API) by this callback.
							// This prevents fetching large resources along with the list of resources.
							getData: ( id ) => fetchDocumentContent( id )
						},

						// More context providers...
					]
				}
			},

			// (Optional) The configuration for AI models used across all AI features (Chat and Review).
			models: {
				defaultModelId: 'gpt-5.4',
				displayedModels: [ 'gpt', 'claude' ],
				showModelSelector: true
			},

			// (Optional) Configure the AI Quick Actions feature by adding a new command.
			quickActions: {
				extraCommands: [
					// An action that opens the AI Chat interface for interactive conversations.
					{
						id: 'explain-like-i-am-five',
						label: 'Explain like I am five',
						displayedPrompt: 'Explain like I am five',
						prompt: 'Explain the following text like I am five years old.',
						type: 'chat'
					},

					// ... More custom actions ...
				],
			},
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="configuration">

## Configuration

<a id="supported-ai-models">

### Supported AI models

CKEditor AI ships with curated models from **OpenAI, Anthropic, and Google** on the [Cloud (SaaS) deployment](ckeditor-ai-deployment.md#cloud-saas). The [On-premises deployment](ckeditor-ai-deployment.md#on-premises) additionally lets you bring your own models from any provider – Google Cloud, Amazon Bedrock, Azure OpenAI, or any OpenAI-compatible endpoint (e.g. OpenRouter, Together AI, self-hosted). By default, an automatically selected model is used for optimal cost and performance.

You can configure the list of available models and the default model using the unified [model configuration](ckeditor-ai-chat.md#configuration), which applies to all AI features (Chat and Review).

Here’s a detailed list of available models with their capabilities:

| **Model**             | **Description**                                                                                                                                                                  | [Web Search](ckeditor-ai-chat.md#web-search) | [Reasoning](ckeditor-ai-chat.md#reasoning) | [Configuration id](ckeditor-ai-chat.md#configuration)                                                                                                   |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto (default)**    | Automatically selects best model for speed, quality, and cost.                                                                                                                   | Yes                                          | Yes                                        | `'auto'` (also `'agent-1'`, learn more about [compatibility versions](../../../../cs/latest/guides/ckeditor-ai/models.md#model-compatibility-versions)) |
| **Custom**            | Bring your own models from major clouds (Google Cloud, Bedrock, Azure OpenAI) or any OpenAI-compatible endpoint. [On-premises only](ckeditor-ai-deployment.md#custom-ai-models). | Per model                                    | Per model                                  | Configured server-side                                                                                                                                  |
| **GPT-5.6 Sol**       | OpenAI’s frontier model for complex professional work and advanced reasoning                                                                                                     | Yes                                          | Yes                                        | `'gpt-5.6-sol'`                                                                                                                                         |
| **GPT-5.6 Terra**     | Balances intelligence, speed, and cost for everyday tasks                                                                                                                        | Yes                                          | Yes                                        | `'gpt-5.6-terra'`                                                                                                                                       |
| **GPT-5.6 Luna**      | OpenAI’s most cost-efficient GPT-5.6 model for high-volume tasks                                                                                                                 | Yes                                          | Yes                                        | `'gpt-5.6-luna'`                                                                                                                                        |
| **GPT-5.5**           | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks                                                                                                    | Yes                                          | Yes                                        | `'gpt-5.5'`                                                                                                                                             |
| **GPT-5.4**           | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks                                                                                                    | Yes                                          | Yes                                        | `'gpt-5.4'`                                                                                                                                             |
| **GPT-5.2**           | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks                                                                                                    | Yes                                          | Yes                                        | `'gpt-5.2'`                                                                                                                                             |
| **GPT-5.1**           | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks                                                                                                    | Yes                                          | Yes                                        | `'gpt-5.1'`                                                                                                                                             |
| **GPT-5**             | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks                                                                                                    | Yes                                          | Yes                                        | `'gpt-5'`                                                                                                                                               |
| **GPT-5 Mini**        | A lightweight version of GPT-5 – faster, more cost-efficient                                                                                                                     | Yes                                          | Yes                                        | `'gpt-5-mini'`                                                                                                                                          |
| **Claude 4.8 Opus**   | Anthropic’s most capable model for extended reasoning and complex tasks                                                                                                          | Yes                                          | Yes                                        | `'claude-opus-4-8'`                                                                                                                                     |
| **Claude 4.7 Opus**   | Anthropic’s most capable model for extended reasoning and complex tasks                                                                                                          | Yes                                          | Yes                                        | `'claude-opus-4-7'`                                                                                                                                     |
| **Claude 5 Sonnet**   | Advanced model with improved creativity, reliability, and reasoning                                                                                                              | Yes                                          | Yes                                        | `'claude-5-sonnet'`                                                                                                                                     |
| **Claude 4.6 Sonnet** | Advanced model with improved creativity, reliability, and reasoning                                                                                                              | Yes                                          | Yes                                        | `'claude-4-6-sonnet'`                                                                                                                                   |
| **Claude 4.5 Haiku**  | Cost-efficient model for quick interactions with improved reasoning                                                                                                              | Yes                                          | Yes                                        | `'claude-4-5-haiku'`                                                                                                                                    |
| **Claude 4.5 Sonnet** | Advanced model with improved creativity, reliability, and reasoning                                                                                                              | Yes                                          | Yes                                        | `'claude-4-5-sonnet'`                                                                                                                                   |
| **Gemini 3.1 Pro**    | Google’s advanced model for versatile problem-solving and research                                                                                                               | Yes                                          | Yes                                        | `'gemini-3-1-pro'`                                                                                                                                      |
| **Gemini 3.5 Flash**  | Lightweight Gemini model for fast, cost-efficient interactions                                                                                                                   | Yes                                          | Yes                                        | `'gemini-3-5-flash'`                                                                                                                                    |
| **Gemini 3 Flash**    | Lightweight Gemini model for fast, cost-efficient interactions                                                                                                                   | Yes                                          | Yes                                        | `'gemini-3-flash'`                                                                                                                                      |
| **Gemini 2.5 Flash**  | Lightweight Gemini model for fast, cost-efficient interactions                                                                                                                   | Yes                                          | Yes                                        | `'gemini-2-5-flash'`                                                                                                                                    |
| **GPT-4.1**           | OpenAI’s model for reliable reasoning, speed, and versatility                                                                                                                    | Yes                                          | No                                         | `'gpt-4.1'`                                                                                                                                             |
| **GPT-4.1 Mini**      | A lighter variant of GPT-4.1 that balances speed and cost while maintaining solid accuracy                                                                                       | Yes                                          | No                                         | `'gpt-4.1-mini'`                                                                                                                                        |

> **Note**
>
> Learn more about model capabilities such as [Web Search](ckeditor-ai-chat.md#web-search) and [Reasoning](ckeditor-ai-chat.md#reasoning).

This list will continue to grow over time. [Share your feedback on model availability](https://ckeditor.com/contact/).

> **Tip**
>
> You can verify which models are compatible with your service version using a dedicated API. [Learn more](../../../../cs/latest/guides/ckeditor-ai/models.md).

<a id="cloud-version-endpoint">

### Cloud version endpoint

While using the cloud version of the CKEditor AI feature, you need to provide the service endpoint.

```js
ai: {
	serviceUrl: 'https://ai.cke-cs.com/v1'
}
```

If you are using the EU cloud region, remember to adjust the endpoint:

```js
ai: {
	serviceUrl: 'https://ai.cke-cs-eu.com/v1'
}
```

<a id="document-id">

### Document ID

The [`config.collaboration.channelId`](../../api/module_collaboration-core_config-RealTimeCollaborationConfig.md#member-channelId) configuration serves as the document identifier corresponding to the edited resource (article, document, etc.) in your application. This ID is essential for maintaining [Chat](ckeditor-ai-chat.md) history, ensuring that AI conversations are properly associated with the specific document being edited. When users interact with AI features, their chat history is preserved and linked to this document ID.

```js
ClassicEditor
	.create( {
		/* ... */

		collaboration: {
			channelId: 'DOCUMENT_ID'
		},

		/* ... */
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

> **Note**
>
> The `channelId` configuration uses the collaboration namespace in the configuration, which may not be immediately understandable for integrators who are not using [collaboration features](../collaboration/context-and-collaboration-features.md#channel-id) in their setup. This namespace is subject to change in future versions as we continue to refine the AI integration architecture.

<a id="default-context">

### Default context

The [`config.ai.defaultContext`](../../api/module_ai_aiconfig-AIConfig.md#member-defaultContext) option attaches contexts – named containers of reusable prompts and reference files kept on the AI service – to the requests made by the AI features. The attached contexts stay invisible to the user. Learn more in the [Context library guide](ckeditor-ai-context-library.md).

<a id="image-analysis">

### Image analysis

The AI service understands images embedded in the document. When the [Chat](ckeditor-ai-chat.md) or [document processing](ckeditor-ai-programmatic.md#document-processing) flow sends the document content, the service downloads the embedded images from their URLs and analyzes them. The AI can then work with the visual content – for example, describe an image, generate a caption for it, or take the image contents into account when editing the surrounding text.

Publicly hosted images require no additional setup. However, if the images live behind authentication (like a private CDN or a token-protected asset server), the download performed by the AI service is anonymous and will fail. Use the [`config.ai.extraHttpHeaders`](../../api/module_ai_aiconfig-AIConfig.md#member-extraHttpHeaders) option to provide HTTP headers that the service will attach when downloading the images:

```js
ai: {
	extraHttpHeaders: [
		{ domain: 'https://assets.example.com/', headers: { authorization: 'Bearer <token>' } }
	]
}
```

Always end each `domain` with a slash, so it cannot match a look-alike host such as `https://assets.example.com.incorrect.example/`. Since authorization tokens expire and rotate, the value can also be a function that returns fresh headers for every request. See the [API reference](../../api/module_ai_aiconfig-AIConfig.md#member-extraHttpHeaders) for the details of both forms.

<a id="track-changes-dependency">

### Track Changes dependency

CKEditor AI can leverage the TrackChanges plugin to enhance the user experience, for instance, by allowing users to turn AI-generated content into suggestions that can later be reviewed, accepted, or rejected. Without the TrackChanges plugin, the CKEditor AI will work, but some functionalities may be limited. For the most complete integration, we highly recommend using TrackChanges along with CKEditor AI.

You can also visually distinguish those AI-authored suggestions from manual edits. See the [Marking AI-generated suggestions](ckeditor-ai-generated-suggestions.md) guide.

> **Note**
>
> Please keep in mind that the `TrackChanges` plugin requires the [`Users` plugin](../collaboration/users.md), and as such, it will require you to provide a minimal user integration, even for non-collaborative setups.
>
> The [sample implementation](#sample-implementation) above shows a basic `UsersIntegration` class that adds a dummy user. For production applications, replace the dummy user with actual user data from your authentication system. Learn more about configuring the `Users` plugin in a [dedicated guide](../collaboration/users.md).

<a id="ui-types-and-positioning">

### UI types and positioning

CKEditor AI gives you flexible options for displaying the AI user interface. The [`config.ai.container`](../../api/module_ai_aiconfig-AIConfig.md#member-container) property allows you to choose from three different UI placement modes:

<a id="sidebar">

#### Sidebar

When in [`AIContainerSidebar`](../../api/module_ai_aiconfig-AIContainerSidebar.md) mode, the AI user interface is displayed in a specific DOM element, allowing you to inject it into your existing user interface.

```js
ClassicEditor
	.create( {
		// ... Other configuration options ...

		ai: {
			container: {
				type: 'sidebar',

				// Existing DOM element to use as the container for the AI user interface.
				element: document.querySelector( '#ai-sidebar-container' )

				// (Optional) The preferred side for positioning the tab buttons.
				side: 'right'
			},
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

In addition to the above, we recommend using the following or similar CSS to style the sidebar container for the AI user interface (tabs) to render optimally:

```css
#ai-sidebar-container .ck.ck-ai-tabs {
	/* An arbitrary fixed width to limit the space consumed by the AI tabs. */
	width: 500px;

	/* A fixed height that enables vertical scrolling (e.g., in the AI Chat feed). */
	height: 800px;
}
```

> **Note**
>
> If the sidebar container is positioned (for instance, `position: sticky`), scrolls, or clips its content, configure an [overlay UI container](#overlay-ui-container) too. Otherwise, the balloons and dialogs of the AI features are positioned relative to that container and drift away from what they are pinned to as the page scrolls.

<a id="overlay">

#### Overlay

When in [`AIContainerOverlay`](../../api/module_ai_aiconfig-AIContainerOverlay.md) mode, the AI user interface is displayed on top of the page, allowing you to position it on your preferred side. This mode is best suited for integrations with limited space.

```js
ClassicEditor
	.create( {
		// ... Other configuration options ...

		ai: {
			container: {
				type: 'overlay',
				side: 'right'
			},
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

The overlay is displayed in the same DOM tree as the editors it covers, or in the [overlay UI container](#overlay-ui-container), when one is configured.

Learn how to [toggle the AI overlay](#toggling-the-ui) using a dedicated toolbar button.

<a id="custom">

#### Custom

When in [`AIContainerCustom`](../../api/module_ai_aiconfig-AIContainerCustom.md) mode, the AI user interface is displayed in a custom way, allowing you to use the building blocks of the AI user interface to create your own and satisfy the specific needs of your application.

```js
ClassicEditor
	.create( {
		// ... Other configuration options ...

		ai: {
			container: {
				type: 'custom'
			},
		}
	} )
	// A custom integration of the AI user interface placing the tab buttons and panels separately in custom containers.
	.then( editor => {
		const tabsPlugin = editor.plugins.get( 'AITabs' );

		for ( const id of tabsPlugin.view.getTabIds() ) {
			const tab = tabsPlugin.view.getTab( id );

			// Display tab button and panel in a custom container.
			myButtonsContainer.appendChild( tab.button.element );
			myPanelContainer.appendChild( tab.panel.element );
		}

		// Tells the AI features which DOM tree their floating UI belongs in.
		tabsPlugin.container = myPanelContainer;
	} )
	.catch( /* ... */ );
```

Setting [`AITabs#container`](../../api/module_ai_aitabs_aitabs-AITabs.md#member-container) moves nothing in this mode – unlike in the [sidebar](#sidebar) and [overlay](#overlay) modes, where the plugin mounts the user interface itself. Here your integration has already placed the tab buttons and panels, and the container only tells the AI features which DOM tree they ended up in.

Until it is set, the floating user interface of the AI features falls back to `document.body`. That is the right place when your containers are in the light DOM, so a light DOM integration works without setting the container at all. Set it whenever the AI user interface **runs inside a shadow root**, where the fallback leaves the balloons and dialogs outside that root, unstyled. Alternatively, configure an [overlay UI container](#overlay-ui-container), which takes precedence over the container.

<a id="overlay-ui-container">

#### Overlay UI container

The floating user interface of the AI features – their balloons, dialogs, and dropdowns – is mounted in a container of its own, called the overlay UI container. By default, it is the DOM tree the AI user interface (`config.ai.container`) lives in: a shadow root when it is in one, `document.body` otherwise. Use the [`config.ai.overlayContainer`](../../api/module_ai_aiconfig-AIConfig.md#member-overlayContainer) option to point it somewhere else:

```js
ClassicEditor
	.create( {
		// ... Other configuration options ...

		ai: {
			container: {
				type: 'sidebar',
				element: document.querySelector( '#ai-sidebar-container' )
			},

			// Balloons, dialogs, and dropdowns of the AI features are mounted here.
			overlayContainer: document.querySelector( '#ai-overlay-container' )
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

Configure it whenever the AI user interface sits in a container that is positioned (for instance, `position: sticky`), scrolls, or clips its content. The floating user interface is placed in `position: absolute` coordinates, which are relative to the nearest positioned ancestor, so in such a container the balloons and dialogs drift away from what they are pinned to as the page scrolls. Point the option at a container of your own at the end of `<body>`, where there is no such ancestor.

We highly recommend you configure it if the AI user interface (`config.ai.container`) **runs inside a shadow root**. Point the option at a separate shadow root attached to a host element at the end of `<body>`, with the editor style sheets [adopted into it](../../getting-started/setup/shadow-dom.md#loading-the-editor-styles). A container nested in the AI user interface’s own tree is subject to the clipping above, while `document.body` has none of the styles.

When `config.ai.overlayContainer` is not set, the shared [`config.ui.overlayContainer`](../../api/module_core_editor_editorconfig-UiConfig.md#member-overlayContainer) option is used instead, if there is one.

> **Note**
>
> CKEditor AI can run inside an open shadow root. Closed shadow roots are not supported. See the [deep dive into shadow DOM support](../../framework/deep-dive/shadow-dom.md) for how the overlay container is resolved, and [Loading the editor styles](../../getting-started/setup/shadow-dom.md#loading-the-editor-styles) for getting the editor style sheets into a root.
>
> A component that puts an editor in a `<slot>` of its own must attach an **open** shadow root – see the known limitations in the deep dive article.

<a id="toggling-the-ui">

### Toggling the UI

The user interface can be easily toggled by the users using the `'toggleAi'` toolbar button. The button becomes available for configuration when the [`AIEditorIntegration`](../../api/module_ai_aieditorintegration_aieditorintegration-AIEditorIntegration.md) plugin is enabled.

The following example shows how to enable the `'toggleAi'` button in the main editor toolbar:

```js
import { ClassicEditor } from 'ckeditor5';
import { /* ... */, AIEditorIntegration } from 'ckeditor5-premium-features';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ AIEditorIntegration, /* ... */ ],

		// Enable the `'toggleAi'` button in the main editor toolbar.
		toolbar: [ 'toggleAi', /* ... */ ],

		ai: {
			container: {
				// ...
			},

			/* ... */
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

If you wish to initially hide the overlay until a user opens it with a button, you can use the [dedicated configuration](#hiding-the-ui-on-initialization).

> **Note**
>
> When the [`AIEditorIntegration`](../../api/module_ai_aieditorintegration_aieditorintegration-AIEditorIntegration.md) plugin is enabled, the `'toggleAi'` button gets displayed automatically in the [menu bar](../../getting-started/setup/menubar.md). To remove this button, please refer to the [menu bar configuration](../../getting-started/setup/menubar.md#configuration) guide.

<a id="hiding-the-ui-on-initialization">

### Hiding the UI on initialization

By default, the AI interface will be visible when the editor is created (and the [related toolbar button](#toggling-the-ui) will be active). If you wish to have it hidden until the user opens it (e.g. via toolbar button), set [`config.ai.container.visibleByDefault`](../../api/module_ai_aiconfig-AIConfig.md#member-container) property to `false`.

<a id="maximizing-the-ui">

### Maximizing the UI

The maximize button in the upper-right corner allows changing the width of the CKEditor AI user interface. Users can use this button to interact with the AI features more comfortably, especially while [chatting](ckeditor-ai-chat.md) and interacting with large chunks of content.

Clicking this button will toggle the `.ck-ai-tabs_maximized` CSS class on the `.ck-ai-tabs` DOM element. The integrator can then style the geometry of the element based on the specific requirements of the integration.

* When the UI is configured in the [sidebar mode](#sidebar), the decision on how to style the maximized state of the user interface is left to the integrator due to many possible integration types and configurations.
* When the UI is configured in the [overlay mode](#overlay), integrators can override the `--ck-ai-tabs-overlay-width-maximized` CSS custom property to change the width of the overlay.

```css
:root {
	/* The CKEditor AI interface will consume 40% of the space when maximized */
	--ck-ai-tabs-overlay-width-maximized: 40%;
}
```

<a id="collapsing-the-tabs">

### Collapsing the tabs

The AI tabs UI can be made collapsible by setting [`config.ai.container.collapsible`](../../api/module_ai_aiconfig-AIConfig.md#member-container) to `true`. When enabled, clicking the active tab button toggles the `.ck-ai-tabs_collapsed` CSS class on the `.ck-ai-tabs` DOM element. The tab buttons remain visible and clickable in the collapsed state, so the panel can be re-expanded by clicking any tab.

Use this class as the hook for any integration-side customization, for example, to keep the tab buttons pinned to the right edge of the sidebar when the panel collapses:

```css
.ai-sidebar {
	display: flex;
	width: 500px;

	.ck.ck-ai-tabs {
		width: 100%;
	}
}

.ai-sidebar:has(.ck-ai-tabs_collapsed) {
	justify-content: flex-end;
}
```

<a id="permissions">

### Permissions

Learn more about the permissions system used in CKEditor AI in a [dedicated guide](../../../../cs/latest/guides/ckeditor-ai/permissions.md).

<a id="chat">

## Chat

Learn more about integrating the Chat feature in a [dedicated guide](ckeditor-ai-chat.md).

<a id="quick-actions">

## Quick Actions

Learn more about integrating the Quick Actions feature in a [dedicated guide](ckeditor-ai-actions.md).

<a id="review">

## Review

Learn more about integrating the Review feature in a [dedicated guide](ckeditor-ai-review.md).

<a id="translate">

## Translate

Learn more about integrating the Translate feature in a [dedicated guide](ckeditor-ai-translate.md).

<a id="multi-root-and-multiple-editors">

## Multi-root and multiple editors

CKEditor AI also works with multi-root editors and across multiple editors sharing a `Context`. See the [AI in multi-root and multi-editor setups](ckeditor-ai-multi-root-multi-editor-support.md) guide for the configuration patterns specific to those setups.

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../llms.txt)