Tabbable

---
title: Tabbable
---

<ComponentPreview name="tabbable-demo" />

<PackageInfo>

## Features

- Ensures consistent tab order between tabbable elements in the editor
- Manages focus transitions between void elements and external DOM elements

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add the tabbable plugin is with the `TabbableKit`, which includes pre-configured `TabbablePlugin` with smart query logic to avoid conflicts with other plugins.

<ComponentSource name="tabbable-kit" />

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { TabbableKit } from '@/components/editor/plugins/tabbable-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...TabbableKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/tabbable
```

### Add Plugin

```tsx
import { TabbablePlugin } from '@platejs/tabbable/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TabbablePlugin,
  ],
});
```

### Configure Plugin

```tsx
import { TabbablePlugin } from '@platejs/tabbable/react';
import { createPlateEditor } from 'platejs/react';
import { KEYS } from 'platejs';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TabbablePlugin.configure({
      options: {
        query: (event) => {
          // Disable when in lists or code blocks
          const inList = editor.api.some({ match: { type: KEYS.li } });
          const inCodeBlock = editor.api.some({ match: { type: KEYS.codeBlock } });
          return !inList && !inCodeBlock;
        },
        globalEventListener: true,
        isTabbable: (tabbableEntry) => 
          editor.api.isVoid(tabbableEntry.slateNode),
      },
    }),
  ],
});
```

- `options.query`: Function to dynamically enable/disable the plugin based on editor state.
- `options.globalEventListener`: When `true`, adds event listener to document instead of editor.
- `options.isTabbable`: Function to determine which elements should be included in tab order.

</Steps>

## Advanced Usage

### Conflicts with Other Plugins

The Tabbable plugin may cause issues with other plugins that handle the `Tab` key, such as:

- Lists
- Code blocks
- Indent plugin

Use the `query` option to disable the Tabbable plugin when the `Tab` key should be handled by another plugin:

```tsx
query: (event) => {
  const inList = editor.api.some({ match: { type: KEYS.li } });
  const inCodeBlock = editor.api.some({ match: { type: KEYS.codeBlock } });
  return !inList && !inCodeBlock;
},
```

Alternatively, if you're using the Indent plugin, you can enable the Tabbable plugin only when a specific type of node is selected, such as voids:

```tsx
query: (event) => !!editor.api.some({
  match: (node) => editor.api.isVoid(node),
}),
```

### Non-void Slate Nodes

One `TabbableEntry` will be created for each tabbable DOM element in the editor, as determined using the [tabbable](https://www.npmjs.com/package/tabbable) NPM package. The list of tabbables is then filtered using `isTabbable`.

By default, `isTabbable` only returns true for entries inside void Slate nodes. You can override `isTabbable` to add support for DOM elements contained in other types of Slate node:

```tsx
// Enable tabbable DOM elements inside CUSTOM_ELEMENT
isTabbable: (tabbableEntry) => (
  tabbableEntry.slateNode.type === CUSTOM_ELEMENT ||
  editor.api.isVoid(tabbableEntry.slateNode)
),
```

### DOM Elements Outside the Editor

In some circumstances, you may want to allow users to tab from the editor to a DOM element rendered outside the editor, such as an interactive popover.

To do this, override `insertTabbableEntries` to return an array of `TabbableEntry` objects, one for each DOM element outside the editor that you want to include in the tabbable list. The `slateNode` and `path` of the `TabbableEntry` should refer to the Slate node the user's cursor will be inside when the DOM element should be tabbable to.

Set the `globalEventListener` option to `true` to make sure the Tabbable plugin is able to return the user's focus to the editor.

For example, if the DOM element appears when a link is selected, the `slateNode` and `path` should be that of the link.

```tsx
// Add buttons inside .my-popover to the list of tabbables
globalEventListener: true,
insertTabbableEntries: (event) => {
  const [selectedNode, selectedNodePath] = editor.api.node(editor.selection);

  return [
    ...document.querySelectorAll('.my-popover > button'),
  ].map((domNode) => ({
    domNode,
    slateNode: selectedNode,
    path: selectedNodePath,
  }));
},
```

## Plugins

### TabbablePlugin

Plugin for managing tab order between tabbable elements.

<API name="TabbablePlugin">
<APIOptions>
  <APIItem name="query" type="(event: KeyboardEvent) => boolean" optional>
    Enable/disable plugin dynamically.
    - **Default:** `() => true`
  </APIItem>
  <APIItem name="globalEventListener" type="boolean" optional>
    Add event listener to document instead of editor.
    - **Default:** `false`
  </APIItem>
  <APIItem name="insertTabbableEntries" type="(event: KeyboardEvent) => TabbableEntry[]" optional>
    Add additional tabbable entries outside editor.
    - **Default:** `() => []`
  </APIItem>
  <APIItem name="isTabbable" type="(tabbableEntry: TabbableEntry) => boolean" optional>
    Determine if element should be tabbable.
    - **Default:** `(tabbableEntry) => editor.api.isVoid(tabbableEntry.slateNode)`
  </APIItem>
</APIOptions>
</API>

## Types

### TabbableEntry

Defines the properties of a tabbable entry.

<API name="TabbableEntry">
<APIAttributes>
  <APIItem name="domNode" type="HTMLElement">
    HTML element representing tabbable entry.
  </APIItem>
  <APIItem name="slateNode" type="TNode">
    Corresponding Slate node.
  </APIItem>
  <APIItem name="path" type="Path">
    Path to Slate node in document.
  </APIItem>
</APIAttributes>
</API>