matthewlipski · Oct 20, 2026 · Oct 22, 2026
diff --git a/examples/03-ui-components/21-block-language/.bnexample.json b/examples/03-ui-components/21-block-language/.bnexample.json
@@ -0,0 +1,8 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "",
+  "tags": ["Intermediate", "Blocks", "UI Components", "Block Side Menu"],
+  "dependencies": {},
+  "pro": false
+}
diff --git a/examples/03-ui-components/21-block-language/README.md b/examples/03-ui-components/21-block-language/README.md
@@ -0,0 +1,9 @@
+# Block languages
+
+This example adds an optional language submenu to the drag handle menu, with English, French, and German. Each block can declare its language for assistive technology or inherit the surrounding language.
+
+**Try it out:** Open a block's drag handle menu and choose a language.
+
+## Relevant Docs
+
+- [Changing the Drag Handle Menu](https://www.blocknotejs.org/docs/react/components/side-menu)
diff --git a/examples/03-ui-components/21-block-language/index.html b/examples/03-ui-components/21-block-language/index.html
@@ -0,0 +1,17 @@
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
+    />
+    <title>Block languages</title>
+    <script>
+      <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/03-ui-components/21-block-language/main.tsx b/examples/03-ui-components/21-block-language/main.tsx
@@ -0,0 +1,11 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./src/App.jsx";
+
+const root = createRoot(document.getElementById("root")!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
diff --git a/examples/03-ui-components/21-block-language/package.json b/examples/03-ui-components/21-block-language/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "@blocknote/example-ui-components-block-language",
+  "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "type": "module",
+  "private": true,
+  "version": "0.12.4",
+  "scripts": {
+    "start": "vite",
+    "dev": "vite",
+    "build:prod": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@blocknote/ariakit": "latest",
+    "@blocknote/core": "latest",
+    "@blocknote/mantine": "latest",
+    "@blocknote/react": "latest",
+    "@blocknote/shadcn": "latest",
+    "@mantine/core": "^9.0.2",
+    "@mantine/hooks": "^9.0.2",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "vite": "^8.0.0"
+  }
+}
diff --git a/examples/03-ui-components/21-block-language/src/App.tsx b/examples/03-ui-components/21-block-language/src/App.tsx
@@ -0,0 +1,70 @@
+import "@blocknote/core/fonts/inter.css";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import {
+  BlockColorsItem,
+  BlockLanguageItem,
+  DragHandleMenu,
+  RemoveBlockItem,
+  SideMenu,
+  SideMenuController,
+  type SideMenuProps,
+  useCreateBlockNote,
+} from "@blocknote/react";
+
+function LanguageDragHandleMenu() {
+  return (
+    <DragHandleMenu>
+      <RemoveBlockItem>Delete</RemoveBlockItem>
+      <BlockColorsItem>Colors</BlockColorsItem>
+      <BlockLanguageItem
+        languages={[
+          { label: "English", language: "en" },
+          { label: "Français", language: "fr" },
+          { label: "Deutsch", language: "de" },
+        ]}
+      >
+        Language
+      </BlockLanguageItem>
+    </DragHandleMenu>
+  );
+}
+
+function LanguageSideMenu(props: SideMenuProps) {
+  return <SideMenu {...props} dragHandleMenu={LanguageDragHandleMenu} />;
+}
+
+export default function App() {
+  const editor = useCreateBlockNote({
+    initialContent: [
+      {
+        type: "paragraph",
+        content: "Open a block's drag handle menu to choose its language.",
+      },
+      {
+        type: "paragraph",
+        props: { lang: "en" },
+        content:
+          "The block looks the same, but screen readers will read content inside with the correct pronounciation for that language.",
+      },
+      {
+        type: "paragraph",
+        props: { lang: "fr" },
+        content: "Bonjour tout le monde !",
+      },
+      {
+        type: "paragraph",
+        props: { lang: "de" },
+        content: "Guten Tag zusammen!",
+      },
+    ],
+  });
+
+  return (
+    <div lang="en">
+      <BlockNoteView editor={editor} sideMenu={false}>
+        <SideMenuController sideMenu={LanguageSideMenu} />
+      </BlockNoteView>
+    </div>
+  );
+}
diff --git a/examples/03-ui-components/21-block-language/tsconfig.json b/examples/03-ui-components/21-block-language/tsconfig.json
@@ -0,0 +1,32 @@
+{
+  "__comment": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "composite": true,
+    "paths": {
+      "@shared/*": ["../../../shared/*"]
+    }
+  },
+  "include": ["."],
+  "__ADD_FOR_LOCAL_DEV_references": [
+    {
+      "path": "../../../packages/core/"
+    },
+    {
+      "path": "../../../packages/react/"
+    }
+  ]
+}
diff --git a/examples/03-ui-components/21-block-language/vite-env.d.ts b/examples/03-ui-components/21-block-language/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/examples/03-ui-components/21-block-language/vite.config.ts b/examples/03-ui-components/21-block-language/vite.config.ts
@@ -0,0 +1,35 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import react from "@vitejs/plugin-react";
+import * as fs from "fs";
+import * as path from "path";
+import { defineConfig } from "vite";
+// https://vitejs.dev/config/
+export default defineConfig(((conf: { command: string }) => ({
+  plugins: [react()],
+  optimizeDeps: {},
+  build: {
+    sourcemap: true,
+  },
+  resolve: {
+    alias:
+      conf.command === "build" ||
+      !fs.existsSync(path.resolve(__dirname, "../../../packages/core/src"))
+        ? {}
+        : ({
+            // The repo-wide alias for the shared test-utils directory (private,
+            // so it only resolves inside the monorepo). Harmless for examples
+            // that don't use it.
+            "@shared": path.resolve(__dirname, "../../../shared/"),
+            // Comment out the lines below to load a built version of blocknote
+            // or, keep as is to load live from sources with live reload working
+            "@blocknote/core": path.resolve(
+              __dirname,
+              "../../../packages/core/src/",
+            ),
+            "@blocknote/react": path.resolve(
+              __dirname,
+              "../../../packages/react/src/",
+            ),
+          } as any),
+  },
+})) as Parameters<typeof defineConfig>[0]);
diff --git a/packages/core/src/blocks/ListItem/CheckListItem/block.test.ts b/packages/core/src/blocks/ListItem/CheckListItem/block.test.ts
@@ -25,6 +25,7 @@ it("renders checkbox as enabled when editor is editable", () => {
     id: "1",
     type: "checkListItem",
     props: {
+      lang: undefined,
       backgroundColor: "default",
       textAlignment: "left",
       textColor: "default",
@@ -46,6 +47,7 @@ it("renders checkbox as disabled when editor is not editable", () => {
     id: "1",
     type: "checkListItem",
     props: {
+      lang: undefined,
       backgroundColor: "default",
       textAlignment: "left",
       textColor: "default",

diff --git a/packages/core/src/blocks/Quote/block.ts b/packages/core/src/blocks/Quote/block.ts
@@ -13,6 +13,7 @@ export const createQuoteBlockConfig = createBlockConfig(
     ({
       type: "quote" as const,
       propSchema: {
+        lang: defaultProps.lang,
         backgroundColor: defaultProps.backgroundColor,
         textColor: defaultProps.textColor,
       },
@@ -28,9 +29,7 @@ export const createQuoteBlockSpec = createBlockSpec(
     },
     parse(element) {
       if (element.tagName === "BLOCKQUOTE") {
-        const { backgroundColor, textColor } = parseDefaultProps(element);
-
-        return { backgroundColor, textColor };
+        return parseDefaultProps(element);
       }
 
       return undefined;

diff --git a/packages/core/src/blocks/defaultProps.ts b/packages/core/src/blocks/defaultProps.ts
@@ -7,6 +7,10 @@ import type { Props, PropSchema } from "../schema/index.js";
 // The dependency from schema on this file doesn't make sense
 
 export const defaultProps = {
+  lang: {
+    default: undefined,
+    type: "string" as const,
+  },
   backgroundColor: {
     default: "default" as const,
   },
@@ -24,6 +28,12 @@ export type DefaultProps = Props<typeof defaultProps>;
 export const parseDefaultProps = (element: HTMLElement) => {
   const props: Partial<DefaultProps> = {};
 
+  if (element.hasAttribute("data-lang")) {
+    props.lang = element.getAttribute("data-lang")!;
+  } else if (element.hasAttribute("lang")) {
+    props.lang = element.lang;
+  }
+
   // If the `data-` attribute is found, set the prop to the value, as this most
   // likely means the parsed element was exported by BlockNote originally.
   // Otherwise, just use whatever is found in the inline styles, if anything.
@@ -55,6 +65,10 @@ export const addDefaultPropsExternalHTML = (
   props: Partial<DefaultProps>,
   element: HTMLElement,
 ) => {
+  if (props.lang !== undefined) {
+    element.lang = props.lang;
+  }
+
   if (
     props.backgroundColor &&
     props.backgroundColor !== defaultProps.backgroundColor.default

diff --git a/packages/core/src/editor/BlockNoteEditor.test.ts b/packages/core/src/editor/BlockNoteEditor.test.ts
@@ -179,6 +179,7 @@ it("sets an initial block id when using Y.js", async () => {
                 {
                   "attrs": {
                     "backgroundColor": "default",
+                    "lang": undefined,
                     "textAlignment": "left",
                     "textColor": "default",
                   },
@@ -207,7 +208,7 @@ it("sets an initial block id when using Y.js", async () => {
   expect(transactionCount).toBe(2);
   // Only after a real modification is made, will the fragment be updated
   expect(fragment.toJSON()).toMatch(
-    /^<blockgroup><blockcontainer id="[^"]+"><paragraph backgroundColor="default" textAlignment="left" textColor="default">Hello<\/paragraph><\/blockcontainer><\/blockgroup>$/,
+    /^<blockgroup><blockcontainer id="[^"]+"><paragraph backgroundColor="default" lang="undefined" textAlignment="left" textColor="default">Hello<\/paragraph><\/blockcontainer><\/blockgroup>$/,
   );
 });
 

diff --git a/packages/core/src/editor/managers/ExtensionManager/extensions.ts b/packages/core/src/editor/managers/ExtensionManager/extensions.ts
@@ -32,6 +32,7 @@ import {
 } from "../../../extensions/index.js";
 import {
   BackgroundColorExtension,
+  LanguageExtension,
   HardBreak,
   KeyboardShortcutsExtension,
   LinkExtension,
@@ -83,6 +84,7 @@ export function getDefaultTiptapExtensions(
       });
     }) as any[]),
 
+    LanguageExtension,
     TextColorExtension,
 
     BackgroundColorExtension,

diff --git a/packages/core/src/extensions/tiptap-extensions/Language/LanguageExtension.ts b/packages/core/src/extensions/tiptap-extensions/Language/LanguageExtension.ts
@@ -0,0 +1,31 @@
+import { Extension } from "@tiptap/core";
+import { Plugin } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+
+// The `lang` prop renders out to a `data-lang` HTML attributes like all other props. To be useful
+// for assistive technologies though, a `lang` attribute has to be rendered. This extension applies
+// the `lang` attribute wherever `data-lang` appears.
+export const LanguageExtension = Extension.create({
+  name: "blockLanguage",
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        props: {
+          decorations: ({ doc }) => {
+            const decorations: Decoration[] = [];
+            doc.descendants((node, pos) => {
+              if (typeof node.attrs.lang === "string") {
+                decorations.push(
+                  Decoration.node(pos, pos + node.nodeSize, {
+                    lang: node.attrs.lang,
+                  }),
+                );
+              }
+            });
+            return DecorationSet.create(doc, decorations);
+          },
+        },
+      }),
+    ];
+  },
+});
diff --git a/packages/core/src/extensions/tiptap-extensions/index.ts b/packages/core/src/extensions/tiptap-extensions/index.ts
@@ -5,3 +5,4 @@ export * from "./TextAlignment/TextAlignmentExtension.js";
 export * from "./TextColor/TextColorExtension.js";
 export * from "./UniqueID/UniqueID.js";
 export * from "./Link/link.js";
+export * from "./Language/LanguageExtension.js";
diff --git a/packages/core/src/i18n/locales/ar.ts b/packages/core/src/i18n/locales/ar.ts
@@ -215,6 +215,9 @@ export const ar: Dictionary = {
   suggestion_menu: {
     no_items_title: "لم يتم العثور على عناصر",
   },
+  language_picker: {
+    default: "تلقائي",
+  },
   color_picker: {
     text_title: "نص",
     background_title: "خلفية",

diff --git a/packages/core/src/i18n/locales/de.ts b/packages/core/src/i18n/locales/de.ts
@@ -250,6 +250,9 @@ export const de: Dictionary = {
   suggestion_menu: {
     no_items_title: "Keine Elemente gefunden",
   },
+  language_picker: {
+    default: "Automatisch",
+  },
   color_picker: {
     text_title: "Text",
     background_title: "Hintergrund",

diff --git a/packages/core/src/i18n/locales/en.ts b/packages/core/src/i18n/locales/en.ts
@@ -230,6 +230,9 @@ export const en = {
   suggestion_menu: {
     no_items_title: "No items found",
   },
+  language_picker: {
+    default: "Auto",
+  },
   color_picker: {
     text_title: "Text",
     background_title: "Background",