---
title: "Format Block Plugin"
description: "Provides a paragraph control to convert block elements between headings, paragraphs, quotes, and code blocks while preserving their content."
metadata:
  - name: keywords
    content: "jodit, format block, formatblock command, headings, paragraph, blockquote, block formatting"
---
# 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:**
```typescript
{
    p: 'Paragraph',
    h1: 'Heading 1',
    h2: 'Heading 2',
    h3: 'Heading 3',
    h4: 'Heading 4',
    blockquote: 'Quote',
    pre: 'Code'
}
```

### `formatBlock.previewProperties`

The list sits outside the editing area, and in iframe mode outside its document, so on its own each preview would take the toolbar's styles. Each preview copies these CSS properties from how the content shows its tag, so a theme's heading fonts and colours show in the list. Lengths become `em`, so they scale with the preview, and size, line height and margins stay with the list.

**Default:** `[]`, so the previews keep the toolbar's styles until you list the properties to copy. The full list the previews can take:
```typescript
[
    'font-family',
    'font-style',
    'font-weight',
    'font-variant',
    'font-stretch',
    'color',
    'letter-spacing',
    'word-spacing',
    'text-transform',
    'text-decoration',
    'text-shadow',
    '-webkit-font-smoothing',
    '-moz-osx-font-smoothing'
]
```

The two smoothing properties matter on macOS, where a theme's `antialiased` or `grayscale` draws its text thinner than the toolbar's. A browser that doesn't know a property leaves it out.

In iframe mode the content's web fonts load only inside the iframe, and the list is in the page. So while `font-family` is in the list, each time the list opens it adds the content's web fonts to the page's `document.fonts` under names only that editor uses, such as `jodit-preview-1-poppins`, and puts those names first in each preview's `font-family`. Nothing else on the page can use them, and they go when the editor is destroyed. A stylesheet from another site, such as Google Fonts, is fetched for its `@font-face` rules, which needs that site to allow it, as Google Fonts does. Where it doesn't, the preview falls back to the page's fonts.

Replace it with `Jodit.atom`, as an array in a plugin's options merges with the default. An empty list keeps the toolbar's styles:

```javascript
Jodit.make('#editor', {
    formatBlock: {
        previewProperties: Jodit.atom(['font-family', 'color'])
    }
});

Jodit.make('#editor', {
    formatBlock: {
        previewProperties: Jodit.atom([])
    }
});
```

### Basic Usage

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

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

### Custom Block Format List

Add additional block formats to the existing list:

```typescript
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`:

```typescript
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:

```typescript
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

```typescript
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:

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

### With Custom Tooltip

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

### Plugin Initialization

1. **Button Registration**: The plugin registers the `paragraph` toolbar button
2. **Command Registration**: Registers a handler for the `formatblock` command
3. **Icon Setup**: Loads the paragraph SVG icon

### Block Format Application

When the `formatblock` command is executed:

1. **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

2. **Synchronization**: Calls `editor.synchronizeValues()` to update the editor state

3. **Return Value**: Returns `false` to prevent default browser behavior

### Current Value Detection

The `value` function determines the current block format:

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

### Button State Update

The `update` function updates the button display:

1. **Value Check**: Gets the current block format value
2. **List Lookup**: Checks if the value exists in the `list` configuration
3. **Text Update**: If `textIcons` is enabled, updates the button text to show the format label
4. **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

### Dropdown Item Rendering

The `childTemplate` function creates preview elements:

1. **Element Creation**: Wraps the label in the actual HTML tag (e.g., `<h1>Label</h1>`)
2. **Style Reset**: Applies `margin:0; padding:0` to prevent layout issues
3. **Content Styles**: Copies `formatBlock.previewProperties` from a hidden probe of the same tag in the editing area, added and removed in one step, so the value and the history don't change. In iframe mode it also adds the content's web fonts to the page under names only that editor uses
4. **Localization**: Translates the label using `editor.i18n()`
5. **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:**
```typescript
editor.execCommand('formatblock', false, tagName);
```

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

**Example:**
```typescript
// 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

1. **No Selection**: When no text is selected, the format is applied to the current block containing the cursor

2. **Multiple Blocks**: When selection spans multiple blocks, each block is converted to the specified format

3. **Nested Blocks**: The plugin identifies the nearest block element and converts it; inline elements are preserved

4. **Invalid Tag Names**: If an invalid or unsupported tag is specified, behavior depends on the browser's `formatBlock` implementation

5. **Lists**: Converting list items may have unexpected results; the plugin works best with standard block elements

6. **Empty Blocks**: Converting empty blocks works correctly and maintains the structure

7. **Block with Complex Content**: All inline formatting, links, images, and other inline elements are preserved when changing block type

8. **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

### withContentFonts()

**withContentFonts**(`editor`, `fontFamily`): `string`

Defined in: [src/plugins/format-block/content-fonts.ts:36](https://github.com/xdan/jodit/blob/main/src/plugins/format-block/content-fonts.ts#L36)

In iframe mode the content's web fonts load only in the iframe, but the
Paragraph list is in the page, so its previews would fall back to the
page's fonts. This adds the content's web fonts to the page under names
only this editor uses, so nothing else on the page can pick them up, and
puts those names first in a preview's `font-family`

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `editor` | [`IJodit`](../interfaces/types.IJodit.html) |
| `fontFamily` | `string` |

#### Returns

`string`

***

### formatBlock()

**formatBlock**(`editor`): `void`

Defined in: [src/plugins/format-block/format-block.ts:21](https://github.com/xdan/jodit/blob/main/src/plugins/format-block/format-block.ts#L21)

Process command - `formatblock`

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `editor` | [`IJodit`](../interfaces/types.IJodit.html) |

#### Returns

`void`