CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-tiptap--extension-heading

A heading extension for TipTap rich text editor providing h1-h6 HTML elements with configurable levels and keyboard shortcuts

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

TipTap Heading Extension

The TipTap Heading Extension provides HTML heading functionality (h1-h6) for TipTap rich text editors. It includes configurable heading levels, keyboard shortcuts, markdown-style input rules, and programmatic commands for setting and toggling headings.

Package Information

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

Core Imports

import { Heading } from "@tiptap/extension-heading";

Default import:

import Heading from "@tiptap/extension-heading";

Named imports:

import { Heading, Level, HeadingOptions } from "@tiptap/extension-heading";

CommonJS:

const { Heading } = require("@tiptap/extension-heading");

Basic Usage

import { Editor } from "@tiptap/core";
import { Heading } from "@tiptap/extension-heading";

// Create editor with heading extension
const editor = new Editor({
  extensions: [
    Heading.configure({
      levels: [1, 2, 3, 4, 5, 6], // Allow all heading levels
      HTMLAttributes: {
        class: 'my-heading',
      },
    }),
  ],
});

// Use commands programmatically
editor.commands.setHeading({ level: 1 }); // Set to h1
editor.commands.toggleHeading({ level: 2 }); // Toggle h2

// Keyboard shortcuts work automatically:
// Mod-Alt-1 through Mod-Alt-6 toggle heading levels

// Markdown input rules work automatically:
// Type "# " for h1, "## " for h2, etc.

Capabilities

Heading Extension Configuration

Creates a configurable heading node extension for TipTap editors with support for h1-h6 HTML elements.

import { Node } from "@tiptap/core";

/**
 * Main heading extension that provides h1-h6 functionality
 */
const Heading: Node<HeadingOptions>;

/**
 * Configuration options for the heading extension
 */
interface HeadingOptions {
  /**
   * Array of allowed heading levels (1-6)
   * @default [1, 2, 3, 4, 5, 6]
   */
  levels: Level[];
  
  /**
   * HTML attributes applied to all heading elements
   * @default {}
   */
  HTMLAttributes: Record<string, any>;
}

/**
 * Valid heading levels corresponding to h1-h6 HTML elements
 */
type Level = 1 | 2 | 3 | 4 | 5 | 6;

Set Heading Command

Programmatically sets the current selection to a heading with the specified level.

/**
 * Sets current selection to a heading node with specified level
 * @param attributes Object containing the heading level
 * @returns Command execution result
 */
editor.commands.setHeading(attributes: { level: Level }): boolean;

Usage Example:

// Set current line/selection to h1
editor.commands.setHeading({ level: 1 });

// Set to h3
editor.commands.setHeading({ level: 3 });

Toggle Heading Command

Toggles between a heading of the specified level and a paragraph, or changes between heading levels.

/**
 * Toggles between heading and paragraph, or changes heading level
 * @param attributes Object containing the heading level to toggle
 * @returns Command execution result
 */
editor.commands.toggleHeading(attributes: { level: Level }): boolean;

Usage Example:

// Toggle h2 - if current node is h2, converts to paragraph
// If current node is paragraph or other heading, converts to h2
editor.commands.toggleHeading({ level: 2 });

// Toggle h1
editor.commands.toggleHeading({ level: 1 });

Keyboard Shortcuts

The extension automatically registers keyboard shortcuts for each configured heading level:

  • Mod-Alt-1: Toggle h1 heading
  • Mod-Alt-2: Toggle h2 heading
  • Mod-Alt-3: Toggle h3 heading
  • Mod-Alt-4: Toggle h4 heading
  • Mod-Alt-5: Toggle h5 heading
  • Mod-Alt-6: Toggle h6 heading

Note: Mod key is Cmd on Mac and Ctrl on Windows/Linux.

Input Rules

The extension supports markdown-style input for creating headings:

  • Type # (hash + space) to create h1
  • Type ## (two hashes + space) to create h2
  • Type ### (three hashes + space) to create h3
  • Continue pattern up to ###### for h6

The input rules create patterns for each configured heading level, where the exact number of hashes corresponds to the heading level (h1=1 hash, h2=2 hashes, etc.).

Configuration Examples

Restrict to Specific Levels

// Only allow h1, h2, and h3
const editor = new Editor({
  extensions: [
    Heading.configure({
      levels: [1, 2, 3],
    }),
  ],
});

Add Custom HTML Attributes

// Add CSS classes and other attributes
const editor = new Editor({
  extensions: [
    Heading.configure({
      levels: [1, 2, 3, 4, 5, 6],
      HTMLAttributes: {
        class: 'prose-heading',
        'data-heading': 'true',
      },
    }),
  ],
});

Documentation Headings Only

// Configure for documentation with h1-h4 only
const editor = new Editor({
  extensions: [
    Heading.configure({
      levels: [1, 2, 3, 4],
      HTMLAttributes: {
        class: 'doc-heading',
      },
    }),
  ],
});

Integration Notes

  • TipTap Core: Requires @tiptap/core as a peer dependency
  • ProseMirror Schema: Creates heading nodes in the ProseMirror document schema
  • HTML Rendering: Renders as semantic h1-h6 HTML elements
  • Block Element: Functions as a block-level element that can contain inline content
  • Accessibility: Maintains proper heading semantics for screen readers and SEO
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@tiptap/extension-heading@3.4.x
Publish Source
CLI
Badge
tessl/npm-tiptap--extension-heading badge