or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-tiptap--extension-bullet-list

Bullet list extension for Tiptap rich text editor that provides unordered list functionality

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

To install, run

npx @tessl/cli install tessl/npm-tiptap--extension-bullet-list@3.4.0

index.mddocs/

@tiptap/extension-bullet-list

@tiptap/extension-bullet-list provides bullet list functionality for Tiptap rich text editors. This extension enables the creation and management of unordered lists with bullet points, integrating seamlessly with Tiptap's headless editor architecture built on ProseMirror.

Package Information

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

Core Imports

import { BulletList } from '@tiptap/extension-bullet-list';
import type { BulletListOptions } from '@tiptap/extension-bullet-list';

Default import:

import BulletList from '@tiptap/extension-bullet-list';

For CommonJS:

const { BulletList } = require('@tiptap/extension-bullet-list');

Type-only import:

import type { BulletListOptions } from '@tiptap/extension-bullet-list';

Import regex pattern from extension-list:

import { bulletListInputRegex } from '@tiptap/extension-list';

Basic Usage

import { Editor } from '@tiptap/core';
import { BulletList } from '@tiptap/extension-bullet-list';
import { ListItem } from '@tiptap/extension-list-item';

const editor = new Editor({
  extensions: [
    BulletList,
    ListItem, // Required dependency
  ],
  content: '<ul><li>First item</li><li>Second item</li></ul>',
});

// Toggle bullet list programmatically
editor.chain().focus().toggleBulletList().run();

// Use keyboard shortcut: Mod-Shift-8
// Or type "- " at the beginning of a line for auto-conversion

Capabilities

BulletList Extension

The main extension class that provides bullet list functionality.

const BulletList: Node<BulletListOptions>;

Configuration Options

Options for customizing bullet list behavior.

interface BulletListOptions {
  /** 
   * The node name for the list items
   * @default 'listItem'
   */
  itemTypeName: string;
  
  /** 
   * HTML attributes to add to the bullet list element
   * @default {}
   */
  HTMLAttributes: Record<string, any>;
  
  /** 
   * Keep the marks when splitting the list
   * @default false
   */
  keepMarks: boolean;
  
  /** 
   * Keep the attributes when splitting the list
   * @default false
   */
  keepAttributes: boolean;
}

Usage with options:

import { BulletList } from '@tiptap/extension-bullet-list';

const editor = new Editor({
  extensions: [
    BulletList.configure({
      HTMLAttributes: {
        class: 'my-bullet-list',
      },
      keepMarks: true,
      keepAttributes: true,
    }),
  ],
});

Commands

Commands available through the editor instance for bullet list manipulation.

interface Commands {
  bulletList: {
    /** Toggle a bullet list */
    toggleBulletList(): Command;
  };
}

Usage:

// Toggle bullet list on current selection
editor.commands.toggleBulletList();

// Chain with other commands
editor.chain().focus().toggleBulletList().run();

Input Rules

The BulletList extension includes automatic input rules that convert typed patterns into bullet lists. The extension automatically converts lines starting with - , + , or * into bullet lists.

const bulletListInputRegex: RegExp;

Usage:

import { bulletListInputRegex } from '@tiptap/extension-list';

// The regex pattern matches: /^\s*([-+*])\s$/
console.log(bulletListInputRegex.test('- ')); // true
console.log(bulletListInputRegex.test('+ ')); // true  
console.log(bulletListInputRegex.test('* ')); // true

Keyboard Shortcuts

Built-in keyboard shortcuts for bullet list operations.

ShortcutAction
Mod-Shift-8Toggle bullet list

Where Mod is Cmd on macOS and Ctrl on other platforms.

Node Properties

The BulletList node has the following characteristics:

  • Name: bulletList
  • Group: block list
  • Content: Accepts one or more list items (defined by itemTypeName option)
  • HTML Parsing: Parses <ul> elements
  • HTML Rendering: Outputs <ul> elements with merged attributes

Dependencies

This extension requires:

  • @tiptap/extension-list: Peer dependency providing the actual BulletList implementation
  • @tiptap/extension-list-item: Required for list item functionality (must be installed separately)
  • @tiptap/core: Core Tiptap framework

Complete installation:

npm install @tiptap/extension-bullet-list @tiptap/extension-list-item @tiptap/core

Error Handling

The extension integrates with Tiptap's command system. Commands return true on success and false on failure:

const success = editor.commands.toggleBulletList();
if (!success) {
  console.log('Failed to toggle bullet list');
}

Advanced Usage

Custom List Item Types

import { BulletList } from '@tiptap/extension-bullet-list';

const editor = new Editor({
  extensions: [
    BulletList.configure({
      itemTypeName: 'customListItem',
    }),
  ],
});

Preserving Formatting

const editor = new Editor({
  extensions: [
    BulletList.configure({
      keepMarks: true,      // Preserve text formatting
      keepAttributes: true, // Preserve node attributes
    }),
  ],
});

Custom HTML Attributes

const editor = new Editor({
  extensions: [
    BulletList.configure({
      HTMLAttributes: {
        class: 'custom-bullet-list',
        'data-type': 'bullet-list',
      },
    }),
  ],
});