Find out what's new in Tiptap Editor 3.0

List Button

Available for free

A fully accessible list button for Tiptap editors. Easily toggle between bullet lists, ordered lists, and task lists with keyboard shortcut support and flexible customization options.

Installation

Add the component via the Tiptap CLI:

npx @tiptap/cli@latest add list-button

Components

<ListButton />

A prebuilt React component that toggles list formatting for a specific list type.

Usage

export default function MyEditor() {
  return (
    <ListButton
      editor={editor}
      type="bulletList"
      text="Bullet List"
      hideWhenUnavailable={true}
      showShortcut={true}
      onToggled={() => console.log('List toggled!')}
    />
  )
}

Props

NameTypeDefaultDescription
editorEditor | nullundefinedThe Tiptap editor instance
typeListTyperequiredThe type of list ("bulletList", "orderedList", "taskList")
textstringundefinedOptional text label for the button
hideWhenUnavailablebooleanfalseHides the button when list toggle is not available
onToggled() => voidundefinedCallback fired after a successful list toggle
showShortcutbooleanfalseShows a keyboard shortcut badge (if available)

Hooks

useList()

A custom hook to build your own list button with full control over rendering and behavior.

Usage

function MyListButton() {
  const { isVisible, isActive, canToggle, handleToggle, label, shortcutKeys, Icon } = useList({
    editor: myEditor,
    type: 'bulletList',
    hideWhenUnavailable: true,
    onToggled: () => console.log('List toggled!'),
  })

  if (!isVisible) return null

  return (
    <button onClick={handleToggle} disabled={!canToggle} aria-label={label} aria-pressed={isActive}>
      <Icon />
      {label}
      {shortcutKeys && <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>}
    </button>
  )
}

Props

NameTypeDefaultDescription
editorEditor | nullundefinedThe Tiptap editor instance
typeListTyperequiredThe type of list to toggle
hideWhenUnavailablebooleanfalseHides the button if list toggle is not available
onToggled() => voidundefinedCallback fired after a successful list toggle

Return Values

NameTypeDescription
isVisiblebooleanWhether the button should be rendered
isActivebooleanIf the specific list type is currently active
canTogglebooleanIf the list toggle is currently allowed
handleToggle() => booleanFunction to toggle list formatting
labelstringAccessible label text for the button
shortcutKeysstringKeyboard shortcut for the specific list type
IconReact.FCIcon component for the list button

Utilities

canToggleList(editor, type, turnInto?)

Checks if a specific list type can be toggled in the current editor state.

import { canToggleList } from '@/registry/tiptap-ui/list-button'

const canToggle = canToggleList(editor, 'bulletList') // Check if can toggle
const canTurnInto = canToggleList(editor, 'bulletList', true) // Check if can turn into bullet list

toggleList(editor, type)

Programmatically toggles list formatting for the specified type.

import { toggleList } from '@/registry/tiptap-ui/list-button'

const success = toggleList(editor, 'orderedList')
if (success) {
  console.log('Ordered list toggled successfully!')
}

isListActive(editor, type)

Checks if a specific list type is currently active.

import { isListActive } from '@/registry/tiptap-ui/list-button'

const active = isListActive(editor, 'taskList')

getListOption(type)

Gets the configuration object for a specific list type.

import { getListOption } from '@/registry/tiptap-ui/list-button'

const option = getListOption('bulletList')
// Returns: { label: "Bullet List", type: "bulletList", icon: ListIcon }

Keyboard Shortcuts

Each list type has its own keyboard shortcut:

  • Cmd/Ctrl + Shift + 8: Toggle bullet list
  • Cmd/Ctrl + Shift + 7: Toggle ordered list
  • Cmd/Ctrl + Shift + 9: Toggle task list

The shortcuts are automatically registered when using either the <ListButton /> component or the useList() hook.

Requirements

Dependencies

  • @tiptap/react - Core Tiptap React integration
  • @tiptap/starter-kit - Basic Tiptap extensions including list support
  • @tiptap/extension-task-list - Task list extension
  • @tiptap/extension-task-item - Task item extension
  • react-hotkeys-hook - Keyboard shortcut management

Referenced Components

  • use-tiptap-editor (hook)
  • button (primitive)
  • badge (primitive)
  • tiptap-utils (lib)
  • list-icon (icon)
  • list-ordered-icon (icon)
  • list-todo-icon (icon)