Docs
Editor Basics
Editor Setup

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 = {
  initialContent?: PartialBlock[];
  domAttributes?: Record<string, string>;
  defaultStyles?: boolean;
  uploadFile?: (file: File) => Promise<string>;
  collaboration?: CollaborationOptions;
  dictionary?: Dictionary;
  schema?: BlockNoteSchema;
};

The hook takes two optional parameters:

options: An object containing options for the editor:

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

domAttributes: An object containing HTML attributes that should be added to various DOM elements in the editor. See Adding DOM Attributes 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.

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

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

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

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

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

💡
Manually creating the editor (BlockNoteEditor.create)

The useCreateBlockNote hook is actually a simple useMemo wrapper around the BlockNoteEditor.create method. You can use this method directly if you want to control the editor lifecycle manually. For example, we do this in the Saving & Loading example to delay the editor creation until some content has been fetched from an external data source.

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;
  imageToolbar?: boolean;
  tableHandles?: 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.

imageToolbar: Whether the Image Toolbar should be enabled.

tableHandles: Whether the Table Handles 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.

💡
Uncontrolled component

Note that the BlockNoteView component is an uncontrolled component (opens in a new tab). This means you don't pass in the editor content directly as a prop. You can use the initialContent option in the useCreateBlockNote hook to set the initial content of the editor (similar to the defaultValue prop in a regular React <textarea>).

BlockNote handles the complexities and performance optimizations of managing editor state internally. You can interact with the editor content using the Editor API.

Editor BasicsDocument Structure