blocknote-native-editor

A pure-native, iOS-first block editor for React Native and Expo. It uses UITextView, TextKit, React Native Fabric, and a headless ProseMirror document engine. It does not use a WebView.

Early preview: iOS and the React Native New Architecture are required. Android and Expo Go are not currently supported.

Requirements

• React Native 0.82 or newer.
• React 19 or newer.
• The React Native New Architecture.
• An Expo development build or a bare React Native iOS app.

The package is tested by its example app with Expo SDK 57 and React Native 0.86.

Install in an Expo app

npm install blocknote-native-editor
npx expo install expo-dev-client

Ensure the New Architecture and an iOS bundle identifier are configured:

{
  "expo": {
    "newArchEnabled": true,
    "ios": {
      "bundleIdentifier": "com.example.myapp"
    }
  }
}

Create an EAS development client:

npx eas-cli build --profile development --platform ios

Then start Metro for the installed client:

npx expo start --dev-client

Expo Go cannot load this package because it includes custom native iOS code. Native package upgrades require a new development build. JavaScript-only app changes can reload through Metro.

No Expo config plugin or manual Podfile changes are required. React Native autolinking discovers the podspec and Fabric Codegen specification.

Basic usage

import {
  BlockNoteView,
  useCreateBlockNote,
} from "blocknote-native-editor";
import { StyleSheet, View } from "react-native";

export default function EditorScreen() {
  const editor = useCreateBlockNote({
    documentId: "notes-main",
    initialContent: [
      { type: "heading", props: { level: 1 }, content: "Notes" },
      { type: "paragraph", content: "Start writing…" },
      { type: "bulletListItem", content: "A bullet" },
      { type: "numberedListItem", content: "A numbered item" },
      {
        type: "toggleListItem",
        content: "Expandable notes",
        children: [{ type: "paragraph", content: "Hidden details" }],
      },
      {
        type: "image",
        props: { url: "https://example.com/image.png", caption: "Example" },
      },
    ],
  });

  return (
    <View style={styles.screen}>
      <BlockNoteView editor={editor} style={styles.editor} />
    </View>
  );
}

const styles = StyleSheet.create({
  screen: {
    flex: 1,
    padding: 16,
    backgroundColor: "#f5f6f8",
  },
  editor: {
    flex: 1,
    backgroundColor: "#ffffff",
    borderColor: "#dfe3e8",
    borderRadius: 12,
    borderWidth: 1,
  },
});

BlockNoteView must receive a stable editor instance. Use useCreateBlockNote() or create and retain one BlockNoteEditor manually. Pass a stable documentId when an app has multiple documents; native toggle expansion state is persisted separately for each document.

Styling

BlockNoteView accepts normal React Native view styles for its outer container:

<BlockNoteView
  editor={editor}
  style={{ flex: 1, backgroundColor: "white", borderRadius: 12 }}
/>

Block-level color and alignment are stored in the document:

const editor = useCreateBlockNote({
  initialContent: [
    {
      type: "paragraph",
      props: {
        textColor: "#243047",
        backgroundColor: "#f4f7ff",
        textAlignment: "center",
      },
      content: [
        {
          type: "text",
          text: "Styled native text",
          styles: { bold: true, textColor: "#7c3aed" },
        },
      ],
    },
  ],
});

Supported inline styles are bold, italic, underline, strike, code, text color, background color, and links. Font families, font sizes, editor insets, paragraph spacing, and list indentation are currently native defaults and do not yet have a public theme prop.

Editor controls

Toolbars are regular React Native UI. Call the editor API from button handlers:

const current = editor.getTextCursorPosition().block;

editor.updateBlock(current, { type: "heading", props: { level: 2 } });
editor.nestBlock();
editor.unnestBlock();
editor.moveBlocksUp();
editor.moveBlocksDown();
editor.undo();
editor.redo();
editor.focus();
editor.blur();

Set editable={false} to render a read-only editor:

<BlockNoteView editor={editor} editable={false} style={{ flex: 1 }} />

Save and load JSON

editor.document is the canonical BlockNote-style document. Serialize it for your API, database, or local storage:

const json = editor.getDocumentJSON({ pretty: true });

editor.loadDocumentJSON(json, {
  addToHistory: false,
  origin: "system",
});

Listen for document changes:

const unsubscribe = editor.onChange((currentEditor) => {
  const json = currentEditor.getDocumentJSON();
  console.log(json);
});

unsubscribe();

Parsing normalizes partial blocks, rejects unsupported block types and duplicate IDs, and guarantees at least one paragraph for an empty document.

Supported blocks

• Paragraphs.
• Headings with levels 1–6, including toggle headings via isToggleable.
• Bullet list items.
• Numbered list items, including nested numbering and a custom start prop.
• Toggle list items with collapsible children.
• File, image, video, and audio blocks with BlockNote-compatible props.
• Arbitrarily nested child blocks.

Media blocks use content: undefined, matching BlockNote JSON. Tap an empty media block to choose an item from Photos or Files, or enter a URL. Picked files are copied into the app's Application Support directory. Images render inline with loading and failure states. Audio and video open in the native system player without leaving the app; file URLs open through iOS. Tap a populated media block once to select and again to open it. A selected media block can be removed with Backspace/Delete, and Return inserts a paragraph after it.

Toggle controls use a 44-point minimum hit target and expose an accessibility action. Their expansion state is local UI state and is not written into BlockNote document JSON.

Rendering performance

The native view tracks document revisions separately from selection revisions. Selection-only updates do not rebuild attributed content, native text edits are acknowledged without rerendering when the optimistic text already matches, and non-structural API updates patch only changed visible blocks. Insertions, removals, moves, nesting changes, and toggle visibility changes safely fall back to a full document render. Selection state also crosses the native bridge as a small payload, so the full block projection is serialized only after document changes.

Bare React Native

After installing the package, install CocoaPods and rebuild the iOS app:

cd ios
pod install
cd ..

Headless core

Consumers that only need the document engine can avoid importing the native view:

import { BlockNoteEditor } from "blocknote-native-editor/core";

License

Mozilla Public License 2.0.