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

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`type`	`ListType`	`required`	The type of list (`"bulletList"`, `"orderedList"`, `"taskList"`)
`text`	`string`	`undefined`	Optional text label for the button
`hideWhenUnavailable`	`boolean`	`false`	Hides the button when list toggle is not available
`onToggled`	`() => void`	`undefined`	Callback fired after a successful list toggle
`showShortcut`	`boolean`	`false`	Shows 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

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`type`	`ListType`	`required`	The type of list to toggle
`hideWhenUnavailable`	`boolean`	`false`	Hides the button if list toggle is not available
`onToggled`	`() => void`	`undefined`	Callback fired after a successful list toggle

Return Values

Name	Type	Description
`isVisible`	`boolean`	Whether the button should be rendered
`isActive`	`boolean`	If the specific list type is currently active
`canToggle`	`boolean`	If the list toggle is currently allowed
`handleToggle`	`() => boolean`	Function to toggle list formatting
`label`	`string`	Accessible label text for the button
`shortcutKeys`	`string`	Keyboard shortcut for the specific list type
`Icon`	`React.FC`	Icon 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)