---
title: Toggle
docs:
  - route: /docs/components/toggle-element
    title: Toggle Element
  - route: /docs/components/toggle-toolbar-button
    title: Toggle Button
---

<ComponentPreview name="toggle-demo" />

<PackageInfo>

## Features

- Add toggles to your document.
  - Toggles are closed by default, and can be opened to reveal the content inside.
- Refer to the [Indent documentation](/docs/indent) for more information.

## Plugin dependencies

- [Indent](/docs/indent)
- [Node Id](/docs/node-id)

</PackageInfo>

## Installation

```bash
npm install @udecode/plate-indent @udecode/plate-node-id @udecode/plate-toggle
```

## Usage

```tsx
// ...
import { ParagraphPlugin } from '@udecode/plate-common/react';
import { NodeIdPlugin } from '@udecode/plate-node-id';
import { IndentPlugin } from '@udecode/plate-indent/react';
import { TogglePlugin } from '@udecode/plate-toggle/react';

const plugins = [
  // ...otherPlugins,
  HeadingPlugin,
  IndentPlugin.configure({
    inject: {
      targetPlugins: [TogglePlugin.key, ParagraphPlugin.key, HEADING_KEYS.h1],
    },
  }),
  NodeIdPlugin,
  TogglePlugin,
];
```

## Plugins

### TogglePlugin

<APIOptions>
<APIItem name="openIds" type="Set<string>" optional>
A set of open toggle IDs.
</APIItem>
<APIItem name="isOpen" type="(toggleId: string) => boolean" optional>
A function to determine if a toggle is open.
</APIItem>
<APIItem name="someClosed" type="(toggleIds: string[]) => boolean" optional>
A function to determine if some toggles are closed.
</APIItem>
</APIOptions>

## API

### editor.api.toggle.toggleIds

Toggles the open state of toggles.

<APIParameters>
  <APIItem name="ids" type="string[]">
    An array of element ids.
  </APIItem>
  <APIItem name="force" type="boolean | null" optional>
    Set to true if you want to expand all toggles regardless of their current
    state. Set to false if you want to collapse all toggles regardless of their
    current state. If null, it will toggle the current state.
  </APIItem>
</APIParameters>

### openNextToggles

Marks the block at the current selection as an open toggle.
Use this function right before inserting a block so that the toggle is expanded upon insertion.

<APIParameters>
  <APIItem name="editor" type="TEditor">
    The editor instance.
  </APIItem>
</APIParameters>

## API Components

### useToggleToolbarButtonState

<APIReturns>
  <APIItem name="pressed" type="boolean">
    A boolean indicating whether the button is pressed or not.
  </APIItem>
</APIReturns>

### useToggleToolbarButton

A behavior hook for the toggle toolbar button.

<APIState>
  <APIItem name="pressed" type="boolean">
    A boolean indicating whether the button is pressed or not.
  </APIItem>
</APIState>

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem parent="props" name="pressed" type="boolean">
        A boolean indicating whether the button is pressed or not.
      </APISubListItem>
      <APISubListItem parent="props" name="onClick" type="function">
        A callback function to handle the click event of the button. It toggles
        the toggle of the specified node type in the editor and focuses the
        editor.
      </APISubListItem>
      <APISubListItem parent="props" name="onMouseDown" type="function">
        A callback function to handle the mouse down event of the button. It
        just prevents default so that focus is not lost when clicking on the
        button.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>

### useToggleButtonState

<APIParameters>
  <APIItem name="toggleId" type="string">
    The id of the toggle element.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="toggleId" type="string">
    The id of the toggle element.
  </APIItem>
  <APIItem name="open" type="boolean">
    A boolean indicating whether the toggle is open (expanded) or not
    (collapsed).
  </APIItem>
</APIReturns>

### useToggleButton

A behavior hook for the toggle button that expands or collapses a toggle element.

<APIParameters>
  <APIItem name="toggleId" type="string">
    The id of the toggle element.
  </APIItem>
  <APIItem name="open" type="boolean">
    A boolean indicating whether the toggle is open (expanded) or not
    (collapsed).
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="toggleId" type="string">
    The id of the toggle element.
  </APIItem>
  <APIItem name="open" type="boolean">
    A boolean indicating whether the toggle is open (expanded) or not
    (collapsed).
  </APIItem>
  <APIItem name="buttonProps" type="object">
    <APISubList>
      <APISubListItem parent="buttonProps" name="onClick" type="function">
        A callback function to handle the click event of the button. It toggles
        the open state of the toggle.
      </APISubListItem>
      <APISubListItem parent="buttonProps" name="onMouseDown" type="function">
        A callback function to handle the mouse down event of the button. It
        just prevents default so that focus is not lost when clicking on the
        button.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>