---
title: "List Button"
description: "Add a button to your Tiptap editor that toggles through bullet, ordered or task lists. More in the docs."
canonical_url: "https://tiptap.dev/docs/ui-components/components/list-button"
---

# List Button

Add a button to your Tiptap editor that toggles through bullet, ordered or task lists. More in the docs.

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.

> **Interactive demo:** [list button](https://template.tiptap.dev/preview/tiptap-ui/list-button)

## Installation

Add the component via the Tiptap CLI:

```bash
npx @tiptap/cli@latest add list-button
```

## Components

### `<ListButton />`

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

#### Usage

```tsx
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

```tsx
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.

```tsx
import { canToggleList } from '@/components/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.

```tsx
import { toggleList } from '@/components/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.

```tsx
import { isListActive } from '@/components/tiptap-ui/list-button'

const active = isListActive(editor, 'taskList')
```

### `getListOption(type)`

Gets the configuration object for a specific list type.

```tsx
import { getListOption } from '@/components/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)