Skip to main content

@bangle.dev/base-components

@bangle.dev/base-components as the name suggests is the core of Bangle and most packages expect it as a peer dependency. To install run:

# peer depsnpm install @bangle.dev/core @bangle.dev/pmnpm install @bangle.dev/base-components

Base Components#

The following is a list of components exported by this package.

blockquote: Component#

Enables blockquote in your editor.

spec(): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?boolean=true
    Toggle the markdown shortcut for creating a blockquote. If enabled, type > followed by a space to create one.

defaultKeys: KeybindingsObject#

  • wrapIn=Ctrl-ArrowRight: wrap text in blockquote.

  • moveDown=Alt-ArrowDown: move blockquote down

  • moveUp=Alt-ArrowUp: move blockquote up

  • emptyCopy=Mod-c: Execute a clipboard copy on the node when the selection is empty.

  • emptyCut=Mod-x: Execute a clipboard cut on the node when the selection is empty.

  • insertEmptyParaAbove=Mod-Shift-Enter: Inserts an empty paragraph above.

  • insertEmptyParaBelow=Mod-Enter: Inserts an empty paragraph below.

commands: CommandObject#

  • queryIsBlockquoteActive(): QueryCommand<boolean>
    Query if the selection is inside a blockquote or not.

Usage

import { blockquote } from '@bangle.dev/base-components';
const specFactory = [  // other specs  blockquote.spec(),];
const plugins = [  // other plugins  blockquote.plugins(),];

bold: Component#

Allows text in your editor to be marked as bold.

spec(): MarkSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?boolean=true
    Toggle the markdown shortcut for creating a bold mark. If enabled, type **text** to create the mark.

defaultKeys: KeybindingsObject#

  • toggleBold = Mod-b: toggle bold mark

commands: CommandObject#

  • toggleBold(): Command
    Toggles bold mark.

  • queryIsBoldActive(): QueryCommand<boolean>
    Query if the selection is inside a bold mark or not.

Usage

import { bold } from '@bangle.dev/base-components';
const specFactory = [  // other specs  bold.spec(),];
const plugins = [  // other plugins  bold.plugins(),];

bulletList: Component#

Enables bulletList <ul/>. Requires node components with names orderedList & listItem to work.

This component implements todo lists by having an attribute todoChecked in any of its children listItem.

spec(): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?boolean=true
    Enable the markdown shortcut for creating a bullet list. If enabled, type -, * or + followed by a space to create a bullet list on an empty paragraph.

  • todoMarkdownShortcut: ?boolean=true
    Enable the markdown shortcut for creating a todo list. Type [ ] or [] followed by a space to create an unchecked todo.

defaultKeys: KeybindingsObject#

  • toggle=Shift-Ctrl-8: Executes toggleBulletList command.

commands: CommandObject#

  • toggleBulletList(): Command
    Convert to a bulletList and if already a bulletList, convert it to a paragraph node.

  • toggleTodoList(): Command
    Convert to a bulletList with todoChecked attribute but if already a bulletList, convert it to a paragraph node.

  • queryIsBulletListActive(): QueryCommand<boolean>
    Query if the selection is inside a bullet list.

  • queryIsTodoListActive(): QueryCommand<boolean>
    Query if the selection has a list item that has todoChecked attribute.

Usage

import { bulletList, listItem, orderedList } from '@bangle.dev/core-components';
const specFactory = [  // other specs  listItem.spec(),  bulletList.spec(),  orderedList.spec(),];
const plugins = [  // other plugins  listItem.plugins(),  bulletList.plugins(),  orderedList.plugins(),];

code: Component#

Allows text in your editor to be marked as code.

spec(): MarkSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • escapeAtEdge: ?Boolean=true
    Allows automatic escaping of code mark at the edges. This particularly helps to escape code mark by pressing left or right arrow key at the edges.

  • markdownShortcut: ?Boolean=true
    Toggle the markdown shortcut for creating a code mark. If enabled, type `text` to create a code mark.

defaultKeys: KeybindingsObject#

  • toggleCode = Mod-`: toggle code mark

commands: CommandObject#

  • toggleCode(): Command
    Toggles code mark.

  • queryIsCodeActive(): QueryCommand<boolean>
    Query if the selection is inside a code mark or not.

Usage

import { code } from '@bangle.dev/base-components';
const specFactory = [  // other specs  code.spec(),];
const plugins = [  // other plugins  code.plugins(),];

codeBlock: Component#

Enables <code/> in your editor.

spec(): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?Boolean=true
    Toggle the markdown shortcut for creating a codeBlock. If enabled, type ``` to create one.

defaultKeys: KeybindingsObject#

  • toCodeBlock=Shift-Ctrl-\: wraps text in codeBlock.

  • moveDown=Alt-ArrowDown: move codeBlock down

  • moveUp=Alt-ArrowUp: move codeBlock up

  • insertEmptyParaAbove=Mod-Shift-Enter: Inserts an empty paragraph above.

  • insertEmptyParaBelow=Mod-Enter: Inserts an empty paragraph below.

commands: CommandObject#

  • queryIsCodeActiveBlock(): QueryCommand<boolean>
    Query if the selection is inside a codeBlock or not.

Usage

import { codeBlock } from '@bangle.dev/base-components';
const specFactory = [  // other specs  codeBlock.spec(),];
const plugins = [  // other plugins  codeBlock.plugins(),];

doc: Component#

Top level node needed by the editor to contain every other node. The spec & plugins for this component are required for Bangle to function, if a spec named doc is not defined, Bangle will automatically default to this one.

spec(): NodeSpec#

Returns a node spec with topNode set to true, read more Your first editor guide.

heading: Component#

Enables headings of various levels in your editor .

spec({ ... }): NodeSpec#

Named parameters:

  • levels: ?number[]=[1,2,3,4,5,6]
    The allowed levels for the heading, think <h1/>, <h2/> and so on. The array must be contiguous and the first element must be 1 and the last element must be less than or equal to 6.

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?Boolean=true
    Toggle the markdown shortcut for heading. If enabled, type # followed by a space to create one a level one heading.

defaultKeys: KeybindingsObject#

  • toH1=Shift-Ctrl-1: Convert a node to heading of level 1. Is a no-op if the level 1 is disallowed.

  • toH2=Shift-Ctrl-2: Convert a node to heading of level 2. Is a no-op if the level 2 is disallowed.

  • toH3=Shift-Ctrl-3: Convert a node to heading of level 3. Is a no-op if the level 3 is disallowed.

  • toH4=Shift-Ctrl-4: Convert a node to heading of level 4. Is a no-op if the level 4 is disallowed.

  • toH5=Shift-Ctrl-5: Convert a node to heading of level 5. Is a no-op if the level 5 is disallowed.

  • toH6=Shift-Ctrl-6: Convert a node to heading of level 6. Is a no-op if the level 6 is disallowed.

  • moveDown=Alt-ArrowDown: move heading down

  • moveUp=Alt-ArrowUp: move heading up

  • emptyCopy=Mod-c: Execute a clipboard copy on the node when the selection is empty.

  • emptyCut=Mod-x: Execute a clipboard cut on the node when the selection is empty.

  • insertEmptyParaAbove=Mod-Shift-Enter: Inserts an empty paragraph above.

  • insertEmptyParaBelow=Mod-Enter: Inserts an empty paragraph below.

  • toggleCollapse: -: Toggle collapsing of heading.

commands: CommandObject#

  • toggleHeading(level: number=3): Command
    Toggles text into heading of a given level and vice versa.

  • queryIsHeadingActive(level:number=3): QueryCommand<boolean>
    Query if the selection is inside a heading of given level.

  • queryIsCollapseActive(): Command
    Query if the current heading is collapsed.

  • collapseHeading(): Command
    Hides every node below that is not heading or has a heading level less than that of the current heading.

  • uncollapseHeading(): Command
    Brings back all the hidden nodes of a collapsed heading. Will only uncollapse shallowly i.e a collapse heading inside of a collapsed heading will not be uncollapsed.

  • toggleHeadingCollapse(): Command
    Collapses an uncollapsed heading and vice versa.

  • uncollapseAllHeadings(): Command
    Uncollapses all headings in the doc. Will also deep uncollapse every heading that was inside of a collapsed heading.

  • insertEmptyParaAbove(): Command
    Insert an empty paragraph above

  • insertEmptyParaBelow(): Command
    Insert an empty paragraph below

On Heading collapse

The heading component also allows you to collapse and uncollapse any content, after the current heading, that is not of type heading or has a heading of level greater than the current heading.

💡 The collapsed data is saved in the node attribute collapseContent, it is also accessible inside the DOM data attribute by accessing data-bangle-attrs.

💡 A collapsed heading will have a class name of bangle-heading-collapsed to allow for styling.

⚠️ For serializing to Markdown you will have to uncollapse your document, since markdown doesn't support collapsing. You should run the commanduncollapseAllHeadings before serializing to markdown.

On top of the collapse commands, the component also exports the following helper functions to help with collapse functionality:

  • listCollapsibleHeading(state: Prosemirror.EditorState): [{node: Prosemirror.Node, pos: number}]
    Lists all the headings that can be collapsed or uncollapsed.

  • listCollapsedHeading(state: Prosemirror.EditorState): [{node: Prosemirror.Node, pos: number}]
    Lists all the headings that are currently collapsed.

  • flattenFragmentJSON(fragmentJSON: Object): Object
    Deep flattens any nested collapsed heading in the object. Bangle internally uses this to implement uncollapseAllHeadings command. Example flattenFragmentJSON(node.attrs.collapseContent).

Usage

import { heading } from '@bangle.dev/base-components';
const specFactory = [  // other specs  heading.spec({ levels: [1, 2] }),];
const plugins = [  // other plugins  heading.plugins(),];

history: Component#

Enables history in your editor, this is a wrapper for the prosemirror's history module. Unless you are overriding this component, it will be included by default.

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • historyOpts: Object
    see the Prosemirror history config docs for the API.

defaultKeys: KeybindingsObject#

  • undo=Mod-x

  • redo=Mod-y Shift-Mod-z

commands: CommandObject#

  • undo(): Command
    Undoes the last step.

  • redo(): Command
    Redoes the last step.

hardBreak: Component#

Enables the <br /> element in your editor.

spec(): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

defaultKeys: KeybindingsObject#

  • insert = Shift-Enter: inserts a hard break

Usage

import { hardBreak } from '@bangle.dev/base-components';const specFactory = [  // other specs  hardBreak.spec(),];
const plugins = [  // other plugins  hardBreak.plugins(),];

horizontalRule: Component#

Enables a horizontal (<hr />) rule component in your editor.

spec(): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?boolean=true
    Toggle the markdown shortcut for creating a horizontalRule. Type --- and ___ to insert a horizontal rule.

Usage

import { horizontalRule } from '@bangle.dev/base-components';
const specFactory = [  // other specs  horizontalRule.spec(),];
const plugins = [  // other plugins  horizontalRule.plugins(),];

image: Component#

Enables images in your editor.

spec(): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • handleDragAndDrop: ?boolean=true
    Toggle the functionality of dragging, dropping and pasting of images into the editor.

  • acceptFileType: ?string=image/*

  • createImageNodes: ?(files: File[], imageType: PMNodeType, view: PMEditorView) -> Promise<ImageNode[]>
    A callback that is called whenever an image is pasted or drop. You are expected to return a promise of corresponding image nodes. If not provided it will run the default defaultCreateImageNodes (see src code) which inlines the image data. If you want to handle saving the image on a server you will want want to provide this param.

Usage

import { image } from '@bangle.dev/base-components';
const specFactory = [  // other specs  image.spec(),];
const plugins = [  // other plugins  image.plugins(),];

italic: Component#

Allows text in your editor to be marked as italic.

spec(): MarkSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?boolean=true
    Toggle the markdown shortcut for creating am italic mark. If enabled, type _text_ to enable italic mark.

defaultKeys: KeybindingsObject#

  • toggleItalic = Mod-i: toggle an italic mark

commands: CommandObject#

  • toggleItalic(): Command
    Toggles italic mark.

  • queryIsItalicActive(): QueryCommand<boolean>
    Query if the selection is inside an italic mark or not.

Usage

import { italic } from '@bangle.dev/base-components';
const specFactory = [  // other specs  italic.spec(),];
const plugins = [  // other plugins  italic.plugins(),];

link: Component#

Allows text in your editor to be marked as link.

spec({ ... }): MarkSpec#

Named parameters:

  • openOnClick: ?boolean=false
    If enabled clicking a link will open the link in new tab. If disabled, clicking a link will set the cursor on it.

plugins(): Plugins#

commands: CommandObject#

  • createLink(href : string): Command
    Creates a link mark on the selection text.

  • updateLink(href : ?string): Command
    Updates a link mark on the selection text with href. Set href to undefined to clear the link mark. If selection is empty, it will update the parent text node.

  • queryLinkAttrs(): QueryCommand<?{href: string, text: string}>
    Returns the details of the link mark in selection.

  • queryIsLinkAllowedInRange(from: number, to: number): QueryCommand<boolean>
    Queries if the range allows for creation of link mark.

  • queryIsLinkActive(): QueryCommand<boolean>
    Queries if the selection is in a link mark.

  • queryIsSelectionAroundLink(): QueryCommand<boolean>
    Queries if the selection is around a link mark.

Usage

import { link } from '@bangle.dev/base-components';
const specFactory = [  // other specs  link.spec(),];
const plugins = [  // other plugins  link.plugins(),];

listItem: Component#

Creates a listItem <li/>. Requires node components with names bulletList and orderedList to work

spec({ ... }): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

defaultKeys: KeybindingsObject#

  • indent=Tab: Indents the listItem

  • outdent=Shift-Tab: Outdents the listItem

  • moveDown=Alt-ArrowDown: move listItem down

  • moveUp=Alt-ArrowUp: move listItem up

  • emptyCopy=Mod-c: Execute a clipboard copy on the node when the selection is empty.

  • emptyCut=Mod-x: Execute a clipboard cut on the node when the selection is empty.

  • insertEmptyListAbove=Mod-Shift-Enter: Insert a new list above the current list and move cursor to it.

  • insertEmptyListBelow=Mod-Enter: Insert a new list below the current list and move cursor to it.

commands: CommandObject#

  • indentListItem(): Command
    Indents list item one level. Can only indent 1 plus the parent's level.

  • outdentListItem(): QueryCommand<boolean>
    Outdents list item one level. If level is root, outdents to a paragraph.

  • moveListItemUp(): QueryCommand<boolean>
    Swap the list item with the one above. If the item above is not a list item, converts the item to paragraph and then moves it.

  • moveListItemDown(): QueryCommand<boolean>
    The opposite of moveListItemUp.

  • insertEmptySiblingListAbove(): Command
    Insert an empty list, at the same nesting level, above the current list

  • insertEmptySiblingListBelow(): Command
    Insert an empty list, at the same nesting level, below the current list.

Usage

import { orderedList, bulletList, listItem  } from '@bangle.dev/base-components';
const specFactory = [  // other specs  listItem.spec(),  orderedList.spec(),  bulletList.spec(),];
const plugins = [  // other plugins  listItem.plugins(),  orderedList.plugins(),  bulletList.spec(),];
// run commandslistItem.insertEmptySiblingListBelow()(state, dispatch);

orderedList: Component#

Enables orderedList <ol/>. Requires node components with names bulletList, listItem to work.

spec(): NodeSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

  • markdownShortcut: ?boolean=true
    Enable the markdown shortcut for creating an ordered list. Type 1. followed by a space to create an ordered list.

defaultKeys: KeybindingsObject#

  • toggle=Shift-Ctrl-9: Executes toggleOrderedList command.

commands: CommandObject#

  • toggleOrderedList(): Command
    Convert to an orderedList and if already an orderedList, convert it to a paragraph node.

  • queryIsSelectionInsideOrderedList(): QueryCommand<boolean>
    Query if the selection is inside an ordered list.

Usage

import { orderedList, bulletList, listItem } from '@bangle.dev/base-components';
const specFactory = [  // other specs  listItem.spec(),  orderedList.spec(),  bulletList.spec(),];
const plugins = [  // other plugins  listItem.plugins(),  orderedList.plugins(),  bulletList.spec(),];

paragraph: Component#

Enables paragraph (<p/> in html) nodes in your editor. The spec for this component are required for Bangle to function, if a spec with a name=paragraph is not specified, Bangle will automatically default to this one.

spec(): NodeSpec#

Returns a spec, read more Your first editor guide.

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

defaultKeys: KeybindingsObject#

  • jumpToStartOfParagraph=Ctrl-a (mac) Ctrl-Home (linux/pc): Executes the jumpToStartOfParagraph command (see commands below).

  • jumpToEndOfParagraph=Ctrl-a (mac) Ctrl-Home (linux/pc): Executes the jumpToEndOfParagraph command (see commands below).

  • moveDown=Alt-ArrowDown: Move paragraph down.

  • moveUp=Alt-ArrowUp: Move paragraph up.

  • emptyCopy=Mod-c: Execute a clipboard copy on the node when the selection is empty.

  • emptyCut=Mod-x: Execute a clipboard cut on the node when the selection is empty.

  • insertEmptyParaAbove=Mod-Shift-Enter: Inserts an empty paragraph above.

  • insertEmptyParaBelow=Mod-Enter: Inserts an empty paragraph below.

  • convertToParagraph=Ctrl-Shift-0: Toggles a node to paragraph and vice versa.

commands: CommandObject#

  • jumpToStartOfParagraph(): Command
    Jumps the cursor to the start of paragraph.

  • jumpToEndOfParagraph(): Command
    Jumps the cursor to the end of paragraph.

  • convertToParagraph(): Command
    Coverts the node in selection to paragraph type.

  • queryIsParagraph(): QueryCommand<boolean>
    Query if it is paragraph under the selection.

  • queryIsTopLevelParagraph(): QueryCommand<boolean>
    Query if it is paragraph under the selection and it is a direct descendant of the top level node, which by default is doc.

  • insertEmptyParagraphAbove(): QueryCommand<boolean>
    Inserts an empty paragraph above the current node.

  • insertEmptyParagraphBelow(): QueryCommand<boolean>
    Inserts an empty paragraph below the current node.

Usage

import { blockquote } from '@bangle.dev/base-components';
const specFactory = [  // other specs  blockquote.spec(),];
const plugins = [  // other plugins  blockquote.plugins(),];

strike: Component#

Allows text in your editor to be marked as strike.

spec(): MarkSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

defaultKeys: KeybindingsObject#

  • toggleStrike = Mod-d: toggle a strike mark

commands: CommandObject#

  • toggleStrike(): Command
    Toggles strike mark.

  • queryIsStrikeActive(): QueryCommand<boolean>
    Query if the selection is inside a strike mark or not.

Usage

import { strike } from '@bangle.dev/base-components';
const specFactory = [  // other specs  strike.spec(),];
const plugins = [  // other plugins  strike.plugins(),];

text: Component#

The text node which the editor uses to wrap the text. The spec for this component are required for Bangle to function, if a spec named text is not defined, Bangle will automatically default to this one.

underline: Component#

Allows text in your editor to be marked with underlined style.

spec(): MarkSpec#

plugins({ ... }): Plugins#

Named parameters:

  • keybindings: ?KeybindingsObject=defaultKeys
    For a list of allowed keys see defaultKeys below.

defaultKeys: KeybindingsObject#

  • toggleUnderline = Mod-u: toggle an underline mark

commands: CommandObject#

  • toggleUnderline(): Command
    Toggles underline mark.

  • queryIsUnderlineActive(): QueryCommand<boolean>
    Query if the selection is inside an underline mark or not.

Usage

import { underline } from '@bangle.dev/base-components';
const specFactory = [  // other specs  underline.spec(),];
const plugins = [  // other plugins  underline.plugins(),];