Tiptap Horizontal Rule Extension

The Tiptap Horizontal Rule Extension provides functionality to insert horizontal rule elements (<hr>) in Tiptap editors. It integrates seamlessly with the Tiptap ecosystem as a block-level node extension with automatic input rules and editor commands.

Package Information

• Package Name: @tiptap/extension-horizontal-rule
• Package Type: npm
• Language: TypeScript
• Installation: npm install @tiptap/extension-horizontal-rule

Core Imports

import { HorizontalRule } from "@tiptap/extension-horizontal-rule";

For CommonJS:

const { HorizontalRule } = require("@tiptap/extension-horizontal-rule");

Default export:

import HorizontalRule from "@tiptap/extension-horizontal-rule";

Basic Usage

import { Editor } from "@tiptap/core";
import { HorizontalRule } from "@tiptap/extension-horizontal-rule";

// Create editor with HorizontalRule extension
const editor = new Editor({
  extensions: [
    HorizontalRule.configure({
      HTMLAttributes: {
        class: "my-horizontal-rule",
      },
    }),
  ],
});

// Insert horizontal rule programmatically
editor.commands.setHorizontalRule();

// Input rules: Type these patterns to auto-insert horizontal rules
// --- (three hyphens)
// —- (em dash + hyphen)  
// ___ (three underscores + space)
// *** (three asterisks + space)

Capabilities

Extension Class

The main extension class that registers the horizontal rule node with Tiptap.

/**
 * Tiptap node extension that allows inserting horizontal rules
 * Created using Node.create<HorizontalRuleOptions>()
 */
const HorizontalRule: Node<HorizontalRuleOptions>;

Configuration Options

Options interface for configuring the HorizontalRule extension.

interface HorizontalRuleOptions {
  /**
   * The HTML attributes for a horizontal rule node.
   * @default {}
   * @example { class: 'foo' }
   */
  HTMLAttributes: Record<string, any>;
}

Editor Commands

Command to insert a horizontal rule at the current cursor position. This command is added to the Tiptap editor instance via TypeScript module augmentation.

/**
 * Add a horizontal rule at the current cursor position
 * Available via editor.commands.setHorizontalRule()
 * @example editor.commands.setHorizontalRule()
 */
function setHorizontalRule(): boolean;

Usage Examples:

// Basic insertion
editor.commands.setHorizontalRule();

// Check if command can execute
if (editor.can().setHorizontalRule()) {
  editor.commands.setHorizontalRule();
}

// Chain with other commands
editor
  .chain()
  .focus()
  .setHorizontalRule()
  .insertContent({ type: 'paragraph' })
  .run();

Input Rules

Automatic text patterns that trigger horizontal rule insertion when typed.

The extension automatically converts these patterns to horizontal rules:

• --- - Three consecutive hyphens
• —- - Em dash followed by hyphen
• ___ - Three underscores followed by space
• *** - Three asterisks followed by space

The input rules are created internally using the nodeInputRule function from @tiptap/core with the regex pattern /^(?:---|—-|___\s|\*\*\*\s)$/ which matches:

• --- at start of line (three hyphens)
• —- at start of line (em dash + hyphen)
• ___ at start of line (three underscores + space)
• *** at start of line (three asterisks + space)

Extension Properties

Key properties and methods of the HorizontalRule extension.

interface HorizontalRuleExtension {
  /** Extension name */
  name: "horizontalRule";
  /** Node group classification */  
  group: "block";
  /** Default options */
  addOptions(): HorizontalRuleOptions;
  /** HTML parsing configuration */
  parseHTML(): Array<{ tag: string }>;
  /** HTML rendering method */
  renderHTML(props: { HTMLAttributes: Record<string, any> }): [string, Record<string, any>];
  /** Command definitions */
  addCommands(): Record<string, () => any>;
  /** Input rule definitions */  
  addInputRules(): any[];
}

HTML Output

Horizontal rules are rendered as <hr> elements. The final HTML attributes are merged from:

1. Extension configuration (HTMLAttributes option)
2. Runtime attributes passed to the render function

<!-- Default output -->
<hr>

<!-- With custom attributes -->
<hr class="custom-hr" data-type="divider">

Integration Notes

Extension Registration

The extension must be registered with a Tiptap editor instance:

import { Editor } from "@tiptap/core";
import { HorizontalRule } from "@tiptap/extension-horizontal-rule";

const editor = new Editor({
  extensions: [
    HorizontalRule,
    // other extensions...
  ],
});

Cursor Positioning

When a horizontal rule is inserted:

1. The cursor automatically moves to the position after the horizontal rule
2. If the horizontal rule is at the document end, a new paragraph is created
3. The view scrolls to keep the cursor visible

Schema Integration

• Node Type: Block-level element
• Content Model: Empty (self-closing)
• Atom: True (cannot contain other content)
• Selectable: True (can be selected as a node)

Dependencies

Required peer dependencies:

• @tiptap/core - Core Tiptap functionality
• @tiptap/pm - ProseMirror integration layer

These must be installed separately and are not bundled with the extension.