Themes and the public page¶
What the public page contains¶
The module renders its own semantic HTML from the stored document: headings, paragraphs, grouped and nested lists, blockquotes, pre > code, dividers, figures for images, video, audio and files, details/summary for toggles, and tables with header rows and cell spans. Every block's outer element carries a class in the blocknote- namespace, and the elements inside a block carry one only where the contract names it. No editor JavaScript and no editor CSS reach the page.
Every heading carries an id made from its words, so a link with a fragment, such as /guide#installation, lands on it; a repeated heading is numbered, so the second Overview is overview-2. The Table of contents block, which the shipped BlockNote format offers, lists the document's headings as links to those ids wherever an author places it.
A code block's <code> carries class="language-<id>" when its language is one the format permits, the convention Prism and highlight.js both read; the module does not highlight anything itself, so a site wanting highlighted code installs one of those libraries, for example through the Prism or highlight.js project.
docs/rendering.md is the contract: the element and class for each block, what a theme may rely on, and what changes only with a major release. Each block has its own template, blocknote-block--<type>.html.twig with the block type in kebab case, so bulletListItem is blocknote-block--bullet-list-item.html.twig. A theme overrides any of them the usual way.
A few things need CSS that markup alone cannot carry. docs/rendering.md section 8 names them and the blocknote/content library that ships them. Its colours are custom properties, --blocknote-color-<name>-text and --blocknote-color-<name>-background, so a theme can restate the palette without replacing the stylesheet.
To turn the stylesheet off entirely, clear Attach the default styles on the formatter, at Manage display for the bundle. A theme that wants to own the palette can instead keep the library and redefine the custom properties.
Search indexing¶
Point Search API, or any other indexer, at the field's rendered output, such as its "Rendered item" data source, or at the processed computed property, the way Layout Builder and Paragraphs are indexed for the same reason. Never index plain_text: it is policy-blind by design, read straight from the stored document without going through the text format, so indexing it makes content the format refuses to show findable by searching for it. ADR 0030 is the record.
Administration themes¶
Claro is supported and tested. The editor is proven against Claro in automated browser tests: the theme's global element rules do not restyle the editor, the editor draws the box Claro draws a text field in, a disabled editor shows Claro's disabled field while a read-only one keeps the ordinary box, the focus ring an author sees is Claro's, and nothing in the editor's stylesheet reaches the rest of the page. Drupal 11.5 deprecates Claro. One layout problem is known: in a narrow window, the editor of an unlimited-cardinality field makes Claro's drag-and-drop table wider than the page, which then scrolls sideways, because the editor needs at least 380 pixels.
Default Admin is supported and tested. It is experimental in Drupal 11.4 and stable from 11.5, where it replaces Claro. The editor is proven against it as against Claro, in its light mode and its dark mode: the theme's global element rules do not restyle the editor, the editor draws the box Default Admin draws a text field in, a disabled editor shows Default Admin's disabled field while a read-only one keeps the ordinary box, the focus ring an author sees is Default Admin's, and nothing in the editor's stylesheet reaches the rest of the page. The tests of what the editor does run in it too, among them that the menus are not clipped inside modal dialogs or off-canvas trays, that the formatting toolbar stays inside an off-canvas tray, and that on a touch device the toolbar's bar above the on-screen keyboard is drawn above such a tray. That the editor follows the page between light and dark color schemes without a reload, as a theme's dark mode switch asks of it through the root element's color-scheme, is tested outside a browser and is not tied to a theme.
Gin is best effort. The Gin coverage here is checked against Gin 5.0.15, commit 356c4b55, most recently on 2026-09-20. That release requires Drupal ^11.2 and therefore runs on 11.4. On it the editor renders correctly in both light and dark mode, the colors of header cells inside an unlimited-cardinality field included. The browser tests that cover Gin are skipped wherever the theme is not installed, which includes continuous integration, so a later Gin release is untested until the check is made by hand again.
The editor is drawn as a form control. No administration theme styles this editor, the way both style core's, so the editor draws its own box: a one-pixel border, the radius the theme rounds a text field by, two pixels in Claro and eight in Gin and Default Admin, and two pixels in a theme that declares none of their tokens, the background of the color scheme it is in, and a minimum height of the five-row textarea it stands in for. For a format restricted to a single paragraph the box is 3rem tall at least, and its text sits 8 pixels in from either side rather than 54, the gutter BlockNote keeps for its side menu. The box is on the editing area itself, so the focus ring the theme draws lands on the box's own edge and an author sees one ring, the one every other field on the form shows. In Claro the border and the background are what Claro gives a text field; in Gin and Default Admin the border is a step from the one their fields have. Both fill an input lighter in dark mode, so the box is a little darker than the fields beside it there. A theme that wants a box of its own declares border, border-radius, background or min-height on .blocknote-editor .bn-editor, or redeclares the --blocknote-editor-* custom properties the module sets. A read-only field draws no box, because it loads no editor. A field disabled after the editor loads, which is what a #states rule does, draws the theme's own disabled background, border and text color instead, so it reads as disabled the way the rest of such a form does, or Claro's own light values where a theme declares neither token. A field made read-only rather than disabled after the editor loads keeps the ordinary box: it stays a tab stop and its content is still read out and still submitted, so it looks the same as it does while editable.
Any administration theme not named above is untested. The editor's own stylesheet is scoped to its container and restores what admin themes take over, so a theme close to Claro is likely to work, but only the themes above are tested, each for what its paragraph says. It also draws a focus ring on the editing area itself, which is what the WCAG 2.1 AA baseline needs where a theme draws none. The rule is written to lose to any theme rule that reaches the editing area, so under Claro, Default Admin and Gin the ring an author sees is still the theme's.
The new-tab marker is hidden by default. While an author edits a link that opens in a new tab, the module draws a small arrow, .blocknote-link-new-tab-glyph, at the end of the link's own text. The module's stylesheet sets it to display: none, so no theme shows it unless it asks to; a theme that wants the hint back adds one rule after the module's own stylesheet loads: .blocknote-link-new-tab-glyph { display: inline; }.
The link form's text inputs draw no theme ring. The URL field, and the link text field that Edit link adds, rely on their caret as the focus indicator, as BlockNote's own link form does, with the row's own background tint added on the focused field; the checkbox and the Save button below them keep the theme's ring, like every other control on the form. ADR 0011 has the reasoning.
Layout Builder¶
The editor mounts in whatever theme renders the Layout Builder tray, which is the site's front-end theme: Layout Builder's routes render in the front-end theme even when the content type is set to use the administration theme. The widget therefore appears there inside a front-end theme, of which only Olivero is checked.
Layout Builder support is not claimed for 1.0. No test covers Layout Builder itself. Olivero, the front-end theme core ships, is checked for the editor mounting on a form it renders, keeping its own styles there and drawing its own focus ring where the theme draws none. The editor may well work in a given front-end theme, and reports are welcome in the issue queue, but no other front-end theme is tested and no fix for one is promised in this release.