Format Block Plugin

Provides block-level formatting controls for the Jodit editor. This plugin allows users to change the type of block elements (paragraphs, headings, quotes, code blocks, etc.) at the cursor position or for selected content.

Features

Convert between different block-level HTML elements
Support for headings (H1-H6), paragraphs, blockquotes, and preformatted text
Customizable list of available block formats
Visual preview of each format in the dropdown
Shows current block format in the toolbar
Highlights active format in the dropdown
Preserves content when changing block types

Control Configuration: `paragraph`

The paragraph control can be customized through the controls configuration:

Properties:

command: 'formatBlock' - The command to execute
list: Object mapping HTML tag names to display labels
childTemplate: Function to render dropdown items with format preview
tooltip: Tooltip text for the button
data.currentValue: Default value when no block is selected (default: 'p')

Default list:

{
    p: 'Paragraph',
    h1: 'Heading 1',
    h2: 'Heading 2',
    h3: 'Heading 3',
    h4: 'Heading 4',
    blockquote: 'Quote',
    pre: 'Code'
}

Basic Usage

The plugin is enabled by default and provides a toolbar button for block formatting:

const editor = Jodit.make('#editor');
// Paragraph button is available in the toolbar

Custom Block Format List

Add additional block formats to the existing list:

const editor = Jodit.make('#editor', {
    controls: {
        paragraph: {
            list: {
                pre: 'Source code',
                h5: 'Heading 5',
                h6: 'Heading 6'
            }
        }
    }
});

Complete List Override

Replace the entire list with custom formats using Jodit.atom:

const editor = Jodit.make('#editor', {
    controls: {
        paragraph: {
            list: Jodit.atom({
                p: 'Paragraph',
                h1: 'Heading 1',
                h2: 'Heading 2',
                h3: 'Heading 3',
                h4: 'Heading 4',
                h5: 'Heading 5',
                h6: 'Heading 6',
                blockquote: 'Quote',
                div: 'Div',
                pre: 'Source code'
            })
        }
    }
});

Custom Display Labels

Customize the labels shown in the dropdown:

const editor = Jodit.make('#editor', {
    controls: {
        paragraph: {
            list: Jodit.atom({
                p: 'Normal Text',
                h1: 'Title',
                h2: 'Subtitle',
                h3: 'Section Header',
                blockquote: 'Citation',
                pre: 'Code Block'
            })
        }
    }
});

Programmatic Usage

const editor = Jodit.make('#editor');

// Convert current block to heading 1
editor.execCommand('formatblock', false, 'h1');

// Convert to paragraph
editor.execCommand('formatblock', false, 'p');

// Convert to blockquote
editor.execCommand('formatblock', false, 'blockquote');

Minimal List

Create a simplified format list with only essential options:

const editor = Jodit.make('#editor', {
    controls: {
        paragraph: {
            list: Jodit.atom({
                p: 'Normal',
                h2: 'Heading',
                blockquote: 'Quote'
            })
        }
    }
});

const editor = Jodit.make('#editor', {
    controls: {
        paragraph: {
            list: {
                p: 'Paragraph',
                h1: 'Heading 1',
                h2: 'Heading 2',
                blockquote: 'Quote'
            },
            tooltip: 'Change paragraph format'
        }
    }
});

Plugin Initialization

Button Registration: The plugin registers the paragraph toolbar button
Command Registration: Registers a handler for the formatblock command
Icon Setup: Loads the paragraph SVG icon

Block Format Application

When the formatblock command is executed:

Style Commit: Uses editor.s.commitStyle() with the element parameter:
- Identifies the current block element containing the cursor or selection
- Replaces the block element's tag name with the specified tag
- Preserves all content and inline formatting within the block
- Handles multiple blocks if selection spans multiple elements
Synchronization: Calls editor.synchronizeValues() to update the editor state
Return Value: Returns false to prevent default browser behavior

Current Value Detection

The value function determines the current block format:

Selection Check: Gets the current cursor position or selection start
Block Search: Uses Dom.closest() to find the nearest block element
Tag Extraction: Returns the lowercase tag name of the block element
Fallback: If no block found, returns the data.currentValue (default: 'p')

Button State Update

The update function updates the button display:

Value Check: Gets the current block format value
List Lookup: Checks if the value exists in the list configuration
Text Update: If textIcons is enabled, updates the button text to show the format label
Returns: false to allow default update behavior

Active State Detection

Child Active State:

Compares the current value with the button's argument (the format being checked)
Highlights the matching format in the dropdown

Button Active State:

Checks if the current value differs from editor.o.enter (the default enter tag)
Verifies the value exists in the list configuration
Activates the button when a non-default format is applied

The childTemplate function creates preview elements:

Element Creation: Wraps the label in the actual HTML tag (e.g., <h1>Label</h1>)
Style Reset: Applies margin:0; padding:0 to prevent layout issues
Localization: Translates the label using editor.i18n()
Preview: Users see how each format looks before selecting it

`formatblock`

Changes the block-level element type at the cursor position or for selected content.

Syntax:

editor.execCommand('formatblock', false, tagName);

Parameters:

tagName (string): The HTML tag name to apply (e.g., 'h1', 'p', 'blockquote')

Example:

// Convert to heading 2
editor.execCommand('formatblock', false, 'h2');

// Convert to blockquote
editor.execCommand('formatblock', false, 'blockquote');

// Convert back to paragraph
editor.execCommand('formatblock', false, 'p');

Edge Cases

No Selection: When no text is selected, the format is applied to the current block containing the cursor
Multiple Blocks: When selection spans multiple blocks, each block is converted to the specified format
Nested Blocks: The plugin identifies the nearest block element and converts it; inline elements are preserved
Invalid Tag Names: If an invalid or unsupported tag is specified, behavior depends on the browser's formatBlock implementation
Lists: Converting list items may have unexpected results; the plugin works best with standard block elements
Empty Blocks: Converting empty blocks works correctly and maintains the structure
Block with Complex Content: All inline formatting, links, images, and other inline elements are preserved when changing block type
Table Cells: Block formatting inside table cells works but is limited to the cell's content

Notes

The plugin uses commitStyle() which intelligently handles block element conversion
The dropdown shows a visual preview of each format by rendering the actual HTML element
The button text can be updated dynamically to show the current format when textIcons is enabled
Block format changes are applied to entire block elements, not just selected text
The Jodit.atom() wrapper is used to completely replace the default list instead of merging with it
Custom block types can be added, but they should be valid HTML block-level elements
The plugin respects the editor's locale settings and translates format labels automatically
Converting between formats preserves all attributes and inline styles of the content
The current format is detected by traversing up the DOM tree to find the nearest block element
If the cursor is not in a block element (edge case), the data.currentValue default is used

formatBlock

formatBlock(editor): void

Process command - formatblock

Parameters

Name	Type
`editor`	`IJodit`

Returns

void

Defined in

jodit/src/plugins/format-block/format-block.ts:21

Font Plugin

Fullsize Plugin

Format Block Plugin

FeaturesFeatures

Control Configuration: Control Configuration: paragraph

Basic UsageBasic Usage

Custom Block Format ListCustom Block Format List

Complete List OverrideComplete List Override

Custom Display LabelsCustom Display Labels

Programmatic UsageProgrammatic Usage

Minimal ListMinimal List

With Custom TooltipWith Custom Tooltip

Plugin InitializationPlugin Initialization

Block Format ApplicationBlock Format Application

Current Value DetectionCurrent Value Detection

Button State UpdateButton State Update

Active State DetectionActive State Detection

Dropdown Item RenderingDropdown Item Rendering

formatblockformatblock

Edge CasesEdge Cases

NotesNotes

formatBlockformatBlock

ParametersParameters

ReturnsReturns

Defined inDefined in