Add a Copilot to the Editor

This guide adds a Copilot chat beside an existing Dollie Editor.

When someone asks for a change, the Copilot shows the result as a preview card. The person can apply it, ask for another version, or ignore it.

What you need

Start with:

• a working PageBuilderEditor;
• your Catalog (the components available in the editor);
• the field definitions for those components;
• a URL that handles chat requests;
• a URL that handles focused AI requests, such as rewriting one field.

The example uses @dollie/ai-sdk for chat. You can use another chat library.

These are the imports used below:

import { createPortal } from 'react-dom';
import { AgentChat, DollieProvider, registerTool } from '@dollie/ai-sdk';
import {
    EditorCopilotApplyProvider,
    EditorCopilotSurfaces,
    registerEditorCopilotTools,
    useAiFill,
    useEditorCopilot,
} from '@dollie_ai/editor';

1. Register the Editor result cards

Add this once, near your chat setup:

registerEditorCopilotTools(registerTool);

This tells the chat how to display Dollie Editor results.

Page suggestions appear as page cards. Section suggestions appear as section cards. Background work, such as reading the Catalog, appears as a small status row.

2. Connect the Copilot to the current editor

Inside the component that already owns your editor state:

const fill = useAiFill({
    endpoint: '/editor/fill',
    headers: () => ({
        'X-CSRF-TOKEN': csrfToken,
    }),
});

const {
    editorProps,
    applyValue,
    contextPayload,
    trail,
    chatHost,
    sidebarSlotRef,
    surfaces,
} = useEditorCopilot({
    editor,
    fill,
    catalog,
    sections: sectionDefinitions,
});

These values each have one job:

Value	What it does
editorProps	Adds the AI actions to the editor
applyValue	Lets preview cards update the current page
contextPayload	Tells the Copilot what is currently on the page
trail	Shows and saves manual and Copilot edits
chatHost	Keeps one copy of the chat mounted
sidebarSlotRef	Marks where the chat belongs in the editor sidebar
surfaces	Configures the field and section preview dialogs

3. Add the chat to the editor

Pass editorProps to your existing editor:

<PageBuilderEditor
    {...editorProps}
    copilotTab={<div ref={sidebarSlotRef} className="h-full min-h-0" />}
/>

Render the chat and the preview dialogs after the editor:

{chatHost &&
    createPortal(
        <EditorCopilotApplyProvider value={applyValue}>
            <DollieProvider _internal _apiUrl="/editor/copilot">
                <AgentChat
                    variant="sidebar"
                    markers={trail}
                    extraBody={{ context: contextPayload }}
                />
            </DollieProvider>
        </EditorCopilotApplyProvider>,
        chatHost,
    )}

<EditorCopilotSurfaces {...surfaces} />

The chat normally appears in the sidebar. When someone opens the AI dialog for one section, the same chat moves into that dialog. The conversation is not restarted.

Passing trail also shows an edit marker below the message that produced a Copilot change. The marker lets the person undo or redo that specific change without rewinding every later edit.

4. Send the current page with each message

contextPayload contains the components on the page, the selected section, and any section draft that is currently open.

Send it with every chat request, as shown in the AgentChat example above. Your chat endpoint should add that information to the latest user message before calling the model.

This prevents the Copilot from answering with an old version of the page.

See Keep the Copilot Up to Date for the server setup.

Change one result card

Register your own component after the defaults:

registerEditorCopilotTools(registerTool);
registerTool('propose_page', { component: ProductPageProposal });

Only the page suggestion changes. The other Editor results keep their default components.

Use another chat library

The Editor components are also available in EDITOR_COPILOT_TOOL_COMPONENTS.

When your chat library renders a tool result, look up the tool name in that object and render the matching component. Wrap the chat in EditorCopilotApplyProvider so the Apply buttons can update the editor.

The chat library needs to pass three values to a result component:

• type: the tool name, such as tool-propose_page;
• input: what the Copilot sent to the tool;
• output: what the tool returned.

Check the complete flow

1. Ask the Copilot to create a page.
2. Preview the result and click Apply.
3. Select one section and ask for a small change.
4. Open the section AI dialog and continue the conversation there.
5. Apply the section change, then undo it.
6. Save the page through your normal save action.

Related

• Give the Copilot Editor Tools
• Review and Apply Suggestions
• Show and Save the Edit Trail
• Keep the Copilot Up to Date