or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-tiptap--extension-heading

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@tiptap/extension-heading@3.4.x

To install, run

npx @tessl/cli install tessl/npm-tiptap--extension-heading@3.4.0

index.mddocs/

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