Getting Started with BlockNote AI

This guide walks you through the steps to add AI functionality to your BlockNote rich text editor.

First, install the @blocknote/xl-ai package:

npm install @blocknote/xl-ai

BlockNote AI uses the the AI SDK to standardize integrating artificial intelligence (AI) models across supported providers.

Setting up the editor

Let's create an editor with the AI Extension enabled:

import { createBlockNoteEditor } from "@blocknote/core";
import { BlockNoteAIExtension } from "@blocknote/xl-ai";
import { en } from "@blocknote/core/locales";
import { en as aiEn } from "@blocknote/xl-ai/locales";
import { createAIExtension } from "@blocknote/xl-ai";
import "@blocknote/xl-ai/style.css"; // add the AI stylesheet

const editor = createBlockNoteEditor({
  dictionary: {
    ...en,
    ai: aiEn, // add default translations for the AI extension
  },
  extensions: [
    createAIExtension({
      transport: new DefaultChatTransport({
        api: `/api/chat`,
      }),
    }),
  ],
  // ... other editor options
});

See the API Reference for more information on the createAIExtension method.

Adding AI UI elements

The next step is to customize the UI elements of your editor. We want to:

add an AI button to the formatting toolbar (shown when selecting text)
add an AI option to the slash menu (shown when typing a /)

We do this by disabling the default FormattingToolbar and SuggestionMenu and adding our own. See Changing UI Elements for more information.

<BlockNoteView
  editor={editor}
  // We're disabling some default UI elements
  formattingToolbar={false}
  slashMenu={false}
>
  {/* Add the AI Command menu to the editor */}
  <AIMenuController />

  {/* Create you own Formatting Toolbar with an AI button,
    (see the full example code below) */}
  <FormattingToolbarWithAI />

  {/* Create you own SlashMenu with an AI option,
    (see the full example code below) */}
  <SuggestionMenuWithAI editor={editor} />
</BlockNoteView>

Backend setup

Now, we'll set up a backend route to handle AI requests that will be forwarded to your LLM provider.

This example follows the basic example from the AI SDK for Next.js:

import { openai } from "@ai-sdk/openai";
import { convertToModelMessages, streamText } from "ai";
import { toolDefinitionsToToolSet } from "@blocknote/xl-ai";

// Allow streaming responses up to 30 seconds
export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages, toolDefinitions } = await req.json();

  const result = streamText({
    model: openai("gpt-4.1"), // see https://ai-sdk.dev/docs/foundations/providers-and-models
    messages: convertToModelMessages(messages),
    tools: toolDefinitionsToToolSet(toolDefinitions),
    toolChoice: "required",
  });

  return result.toUIMessageStreamResponse();
}

See Backend integrations for more information on how to integrate BlockNote AI with your backend.

Full Example

See the full example code and live demo. Select some text and click the AI (stars) button, or type /ai anywhere in the editor to access AI functionality.

GitHub

StackBlitz

import { BlockNoteEditor, filterSuggestionItems } from "@blocknote/core";
import "@blocknote/core/fonts/inter.css";
import { en } from "@blocknote/core/locales";
import { BlockNoteView } from "@blocknote/mantine";
import "@blocknote/mantine/style.css";
import {
  FormattingToolbar,
  FormattingToolbarController,
  getDefaultReactSlashMenuItems,
  getFormattingToolbarItems,
  SuggestionMenuController,
  useCreateBlockNote,
} from "@blocknote/react";
import {
  AIMenuController,
  AIToolbarButton,
  createAIExtension,
  getAISlashMenuItems,
} from "@blocknote/xl-ai";
import { en as aiEn } from "@blocknote/xl-ai/locales";
import "@blocknote/xl-ai/style.css";

import { DefaultChatTransport } from "ai";
import { getEnv } from "./getEnv";

const BASE_URL =
  getEnv("BLOCKNOTE_AI_SERVER_BASE_URL") || "https://localhost:3000/ai";

export default function App() {
  // Creates a new editor instance.
  const editor = useCreateBlockNote({
    dictionary: {
      ...en,
      ai: aiEn, // add default translations for the AI extension
    },
    // Register the AI extension
    extensions: [
      createAIExtension({
        transport: new DefaultChatTransport({
          // URL to your backend API, see example source in `packages/xl-ai-server/src/routes/regular.ts`
          api: `${BASE_URL}/regular/streamText`,
        }),
      }),
    ],
    // We set some initial content for demo purposes
    initialContent: [
      {
        type: "heading",
        props: {
          level: 1,
        },
        content: "Open source software",
      },
      {
        type: "paragraph",
        content:
          "Open source software refers to computer programs whose source code is made available to the public, allowing anyone to view, modify, and distribute the code. This model stands in contrast to proprietary software, where the source code is kept secret and only the original creators have the right to make changes. Open projects are developed collaboratively, often by communities of developers from around the world, and are typically distributed under licenses that promote sharing and openness.",
      },
      {
        type: "paragraph",
        content:
          "One of the primary benefits of open source is the promotion of digital autonomy. By providing access to the source code, these programs empower users to control their own technology, customize software to fit their needs, and avoid vendor lock-in. This level of transparency also allows for greater security, as anyone can inspect the code for vulnerabilities or malicious elements. As a result, users are not solely dependent on a single company for updates, bug fixes, or continued support.",
      },
      {
        type: "paragraph",
        content:
          "Additionally, open development fosters innovation and collaboration. Developers can build upon existing projects, share improvements, and learn from each other, accelerating the pace of technological advancement. The open nature of these projects often leads to higher quality software, as bugs are identified and fixed more quickly by a diverse group of contributors. Furthermore, using open source can reduce costs for individuals, businesses, and governments, as it is often available for free and can be tailored to specific requirements without expensive licensing fees.",
      },
    ],
  });

  // Renders the editor instance using a React component.
  return (
    <div>
      <BlockNoteView
        editor={editor}
        // We're disabling some default UI elements
        formattingToolbar={false}
        slashMenu={false}
      >
        {/* Add the AI Command menu to the editor */}
        <AIMenuController />

        {/* We disabled the default formatting toolbar with `formattingToolbar=false` 
        and replace it for one with an "AI button" (defined below). 
        (See "Formatting Toolbar" in docs)
        */}
        <FormattingToolbarWithAI />

        {/* We disabled the default SlashMenu with `slashMenu=false` 
        and replace it for one with an AI option (defined below). 
        (See "Suggestion Menus" in docs)
        */}
        <SuggestionMenuWithAI editor={editor} />
      </BlockNoteView>
    </div>
  );
}

// Formatting toolbar with the `AIToolbarButton` added
function FormattingToolbarWithAI() {
  return (
    <FormattingToolbarController
      formattingToolbar={() => (
        <FormattingToolbar>
          {...getFormattingToolbarItems()}
          {/* Add the AI button */}
          <AIToolbarButton />
        </FormattingToolbar>
      )}
    />
  );
}

// Slash menu with the AI option added
function SuggestionMenuWithAI(props: {
  editor: BlockNoteEditor<any, any, any>;
}) {
  return (
    <SuggestionMenuController
      triggerCharacter="/"
      getItems={async (query) =>
        filterSuggestionItems(
          [
            ...getDefaultReactSlashMenuItems(props.editor),
            // add the default AI slash menu items, or define your own
            ...getAISlashMenuItems(props.editor),
          ],
          query,
        )
      }
    />
  );
}

// helper function to get env variables across next / vite
// only needed so this example works in BlockNote demos and docs
export function getEnv(key: string) {
  const env = (import.meta as any).env
    ? {
        BLOCKNOTE_AI_SERVER_API_KEY: (import.meta as any).env
          .VITE_BLOCKNOTE_AI_SERVER_API_KEY,
        BLOCKNOTE_AI_SERVER_BASE_URL: (import.meta as any).env
          .VITE_BLOCKNOTE_AI_SERVER_BASE_URL,
      }
    : {
        BLOCKNOTE_AI_SERVER_API_KEY:
          process.env.NEXT_PUBLIC_BLOCKNOTE_AI_SERVER_API_KEY,
        BLOCKNOTE_AI_SERVER_BASE_URL:
          process.env.NEXT_PUBLIC_BLOCKNOTE_AI_SERVER_BASE_URL,
      };

  const value = env[key as keyof typeof env];
  return value;
}

Getting Started with BlockNote AI

Setting up the editor

Adding AI UI elements

Backend setup

Full Example

On this page

Learn

Collaborate

Community

Legal

Theme