Custom Schemas
By default, BlockNote documents support different kind of blocks, inline content and text styles (see default schema). However, you can extend BlockNote and create custom schemas to support your own blocks, inline content and text styles.
Custom Blocks
Blocks are the main elements of a document, such as paragraphs, headings, lists, etc.
Custom Inline Content
Inline Content are elements that can be inserted inside a text block, such as links, mentions, tags, etc.
Custom Styles
Text Styles are properties that can be applied to a piece of text, such as bold, italic, underline, etc.
Creating your own schema
Once you have defined your custom blocks (see the links above), inline content or styles, you can create a schema and pass this to the initialization of the editor. There are two ways to create a new schema.
Extending an existing schema
You can call BlockNoteSchema.extend to add custom blocks, inline content, or styles to an existing schema. While this works for any existing schema, it's most common to use this to extend the default schema.
// Creates an instance of the default schema when nothing is passed to
// `BlockNoteSchema.create`.
const schema = BlockNoteSchema.create()
// Adds custom blocks, inline content, or styles to the default schema.
.extend({
blockSpecs: {
// Add your own custom blocks:
customBlock: CustomBlock,
...
},
inlineContentSpecs: {
// Add your own custom inline content:
customInlineContent: CustomInlineContent,
...
},
styleSpecs: {
// Add your own custom styles:
customStyle: CustomStyle,
...
},
});Creating a schema from scratch
Passing custom blocks, inline content, or styles directly into BlockNoteSchema.create will produce a new schema with only the things you pass. This can be useful if you only need a few basic things from the default schema, and intend to implement everything else yourself.
const schema = BlockNoteSchema.create({
blockSpecs: {
// Add only the default paragraph block:
paragraph: defaultBlockSpecs.paragraph,
// Add your own custom blocks:
customBlock: CustomBlock,
...
},
inlineContentSpecs: {
// Add only the default text inline content:
text: defaultInlineContentSpecs.text,
// Add your own custom inline content:
customInlineContent: CustomInlineContent,
...
},
styleSpecs: {
// Add only the default bold style:
bold: defaultStyleSpecs.bold,
// Add your own custom styles:
customStyle: CustomStyle,
...
},
});Using your own schema
Once you've created an instance of your schema using BlockNoteSchema.create or BlockNoteSchema.extend, you can pass it to the schema option of your BlockNoteEditor (BlockNoteEditor.create or useCreateBlockNote):
const editor = useCreateBlockNote({
schema,
});Usage with TypeScript
In contrast to most other editors, BlockNote has been designed for full TypeScript compatibility. This means you can get full type safety and autocompletion even when using a custom schema.
By default, the methods, hooks, and types exposed by the API assume you're using the default, built-in schema. If you're using a custom schema, there are 3 ways to get full type safety:
Methods that accept an optional schema parameter
Some methods, like the useBlockNoteEditor hook, take an optional schema?: BlockNoteSchema parameter. If you're using a custom schema, you should pass it here to make sure the return type is correctly typed.
Manual typing of types
If you're using types like BlockNoteEditor, Block, PartialBlock directly, you can get the correctly typed variants like this:
type MyBlock = Block<
typeof schema.blockSchema,
typeof schema.inlineContentSchema,
typeof schema.styleSchema
>;Or even simpler, use the shorthands exposed by the schema:
type MyBlockNoteEditor = typeof schema.BlockNoteEditor;
type MyBlock = typeof schema.Block;
type MyPartialBlock = typeof schema.PartialBlock;Automatically override all default types (experimental)
Alternatively, the easiest way to get full type safety without any additional work is to override all default types with your custom schema, by using a custom type definition file. See this example blocknote.d.ts. This is an experimental feature - we would love to hear your feedback on this approach.