Editor Setup

You can customize your editor when you instantiate it. Let's take a closer looks at the basic methods and components to set up your BlockNote editor.

useCreateBlockNote hook

Create a new BlockNoteEditor by calling the useCreateBlockNote hook. This instantiates a new editor and its required state. You can later interact with the editor using the Editor API and pass it to the BlockNoteView component.

function useCreateBlockNote(
  options?: BlockNoteEditorOptions,
  deps?: React.DependencyList = [],
): BlockNoteEditor;
 
type BlockNoteEditorOptions = {
  animations?: boolean;
  collaboration?: CollaborationOptions;
  comments?: CommentsConfig;
  defaultStyles?: boolean;
  dictionary?: Dictionary;
  disableExtensions?: string[];
  domAttributes?: Record<string, string>;
  dropCursor?: (opts: {
    editor: BlockNoteEditor;
    color?: string | false;
    width?: number;
    class?: string;
  }) => Plugin;
  initialContent?: PartialBlock[];
  resolveFileUrl: (url: string) => Promise<string>
  schema?: BlockNoteSchema;
  setIdAttribute?: boolean;
  sideMenuDetection?: "viewport" | "editor";
  tabBehavior?: "prefer-navigate-ui" | "prefer-indent"
  trailingBlock?: boolean;
  uploadFile?: (file: File) => Promise<string>;
};

The hook takes two optional parameters:

options: An object containing options for the editor:

animations: Whether changes to blocks (like indentation, creating lists, changing headings) should be animated or not. Defaults to true.

collaboration: Options for enabling real-time collaboration. See Real-time Collaboration for more info.

comments: Configuration for the comments feature, requires a threadStore. See Comments for more.

defaultStyles: Whether to use the default font and reset the styles of <p>, <li>, <h1>, etc. elements that are used in BlockNote. Defaults to true if undefined.

dictionary: Provide strings for localization. See the Localization / i18n example and Custom Placeholders.

disableExtensions (advanced): Disables TipTap extensions used in BlockNote by default, based on their names.

domAttributes: An object containing HTML attributes that should be added to various DOM elements in the editor. See Adding DOM Attributes for more.

dropCursor: A replacement indicator to use when dragging and dropping blocks. Uses the ProseMirror drop cursor (opens in a new tab), or a modified version when Column Blocks are enabled.

initialContent: The content that should be in the editor when it's created, represented as an array of Partial Blocks.

resolveFileUrl: Function to resolve file URLs for display/download. Useful for creating authenticated URLs or implementing custom protocols.

resolveUsers: Function to resolve user information for comments. See Comments for more.

schema: The editor schema if you want to extend your editor with custom blocks, styles, or inline content Custom Schemas.

setIdAttribute: Whether to render an id HTML attribute on blocks as well as a data-id attribute. Defaults to false.

sideMenuDetection: Determines whether the mouse cursor position is locked to the editor bounding box for showing the Block Side Menu and block drag & drop. When set to viewport, the Side Menu will be shown next to the nearest block to the cursor, regardless of where it is in the viewport. Dropping blocks will also be locked to the editor bounding box. Otherwise, the Side Menu will only be shown when the cursor is within the editor bounds, and blocks can only be dropped when hovering the editor. In order to use multiple editors, must be set to editor. Defaults to viewport.

tabBehavior: Determines whether pressing the tab key should navigate toolbars for keyboard accessibility. When set to "prefer-navigate-ui, the user can navigate toolbars using Tab. Pressing Escape re-focuses the editor, and Tab now indents blocks. "prefer-indent" causes Tab to always indent blocks. Defaults to prefer-navigate-ui.

trailingBlock: An option which user can pass with false value to disable the automatic creation of a trailing new block on the next line when the user types or edits any block. Defaults to true if undefined.

uploadFile: A function which handles file uploads and eventually returns the URL to the uploaded file. Used for Image blocks.

deps: Dependency array that's internally passed to useMemo. A new editor will only be created when this array changes.

Rendering the Editor with <BlockNoteView>

Use the <BlockNoteView> component to render the BlockNoteEditor instance you just created:

const editor = useCreateBlockNote();
 
return <BlockNoteView editor={editor} />;

Props

There are a number of additional props you can pass to BlockNoteView. You can find the full list of these below:

export type BlockNoteViewProps = {
  editor: BlockNoteEditor;
  editable?: boolean;
  onSelectionChange?: () => void;
  onChange?: () => void;
  theme?:
    | "light"
    | "dark"
    | Theme
    | {
        light: Theme;
        dark: Theme;
      };
  formattingToolbar?: boolean;
  linkToolbar?: boolean;
  sideMenu?: boolean;
  slashMenu?: boolean;
  emojiPicker?: boolean;
  filePanel?: boolean;
  tableHandles?: boolean;
  comments?: boolean;
  children?:
} & HTMLAttributes<HTMLDivElement>;

editor: The BlockNoteEditor instance to render.

editable: Whether the editor should be editable.

onSelectionChange: Callback fired when the editor selection changes.

onChange: Callback fired when the editor content (document) changes.

theme: The editor's theme, see Themes for more about this.

formattingToolbar: Whether the Formatting Toolbar should be enabled.

linkToolbar: Whether the Link Toolbar should be enabled.

sideMenu: Whether the Block Side Menu should be enabled.

slashMenu: Whether the Slash Menu should be enabled.

emojiPicker: Whether the Emoji Picker should be enabled.

filePanel: Whether the File Toolbar should be enabled.

tableHandles: Whether the Table Handles should be enabled.

comments: Whether the default comments UI feature should be enabled.

children: Pass child elements to the BlockNoteView to create or customize toolbars, menus, or other UI components. See UI Components for more.

Additional props passed are forwarded to the HTML div element BlockNote renders internally.