List Button
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 extensionreact-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)