tiptap/docs/api/extensions.md

75 lines
6.8 KiB
Markdown
Raw Normal View History

---
tableOfContents: true
---
2020-08-13 15:47:32 +08:00
# Extensions
2020-08-21 04:20:56 +08:00
## Introduction
2021-10-20 04:30:45 +08:00
Extensions add new capabilities to Tiptap and youll read the word extension here very often. Actually, there are literal Extensions. Those cant add to the schema, but can add functionality or change the behaviour of the editor.
2021-02-12 06:37:41 +08:00
There are also some extensions with more capabilities. We call them [nodes](/api/nodes) and [marks](/api/marks) which can render content in the editor.
2020-11-03 23:13:13 +08:00
## List of provided extensions
2021-06-23 03:28:20 +08:00
| Title | StarterKit ([view](/api/extensions/starter-kit)) | Source Code |
| ----------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| [BubbleMenu](/api/extensions/bubble-menu) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-bubble-menu/) |
2021-06-23 03:28:20 +08:00
| [CharacterCount](/api/extensions/character-count) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-character-count/) |
| [Collaboration](/api/extensions/collaboration) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-collaboration/) |
| [CollaborationCursor](/api/extensions/collaboration-cursor) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-collaboration-cursor/) |
| [Color](/api/extensions/color) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-color/) |
2021-06-23 03:28:20 +08:00
| [Dropcursor](/api/extensions/dropcursor) | Included | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-dropcursor/) |
| [FloatingMenu](/api/extensions/floating-menu) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-floating-menu/) |
2021-06-23 03:28:20 +08:00
| [Focus](/api/extensions/focus) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-focus/) |
| [FontFamily](/api/extensions/font-family) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-font-family/) |
| [Gapcursor](/api/extensions/gapcursor) | Included | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-gapcursor/) |
| [History](/api/extensions/history) | Included | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-history/) |
2023-03-15 20:39:13 +08:00
| [InvisibleCharacters](/api/extensions/invisible-characters) | | Requires a Tiptap Pro subscription |
2023-03-16 00:05:59 +08:00
| [Mathematics](/api/extensions/mathematics) | | Requires a Tiptap Pro subscription |
2021-06-23 03:28:20 +08:00
| [Placeholder](/api/extensions/placeholder) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-placeholder/) |
| [StarterKit](/api/extensions/starter-kit) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/starter-kit/) |
2021-06-23 03:28:20 +08:00
| [TextAlign](/api/extensions/text-align) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-text-align/) |
| [Typography](/api/extensions/typography) | | [GitHub](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-typography/) |
2022-11-08 04:41:00 +08:00
| [UniqueID](/api/extensions/unique-id) | | Requires a Tiptap Pro subscription |
2020-11-03 23:13:13 +08:00
2021-05-07 00:41:22 +08:00
You dont have to use it, but we prepared a `@tiptap/starter-kit` which includes the most common extensions. Read more about [`StarterKit`](/guide/configuration#default-extensions).
2020-11-03 23:13:13 +08:00
Also a list of community extensions can be found in the [Awesome Tiptap Repository](https://github.com/ueberdosis/awesome-tiptap#community-extensions). There is also a [Discussion Thread](https://github.com/ueberdosis/tiptap/discussions/2973) about community extensions.
2021-01-21 00:58:53 +08:00
## How extensions work
2021-10-20 04:30:45 +08:00
Although Tiptap tries to hide most of the complexity of ProseMirror, its built on top of its APIs and we recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/) for advanced usage. Youll have a better understanding of how everything works under the hood and get more familiar with many terms and jargon used by Tiptap.
2021-01-21 00:58:53 +08:00
Existing [nodes](/api/nodes), [marks](/api/marks) and [extensions](/api/extensions) can give you a good impression on how to approach your own extensions. To make it easier to switch between the documentation and the source code, we linked to the file on GitHub from every single extension documentation page.
2022-11-08 04:41:00 +08:00
We recommend to start with customizing existing extensions first, and create your own extensions with the gained knowledge later. Thats why all the examples below extend existing extensions, but all examples will work on newly created extensions aswell.
2021-01-21 00:58:53 +08:00
2020-11-03 23:13:13 +08:00
## Create a new extension
2022-09-01 19:57:20 +08:00
Youre free to create your own extensions for Tiptap. Here is the boilerplate code thats needed to create and register your own extension:
2020-11-03 23:13:13 +08:00
```js
2020-11-16 17:03:12 +08:00
import { Extension } from '@tiptap/core'
2020-11-03 23:13:13 +08:00
2020-11-16 17:03:12 +08:00
const CustomExtension = Extension.create({
2020-11-03 23:13:13 +08:00
// Your code here
})
const editor = new Editor({
extensions: [
// Register your custom extension with the editor.
2020-11-16 17:03:12 +08:00
CustomExtension,
2020-11-03 23:13:13 +08:00
// … and dont forget all other extensions.
2020-11-16 17:03:12 +08:00
Document,
Paragraph,
Text,
2020-11-03 23:13:13 +08:00
// …
],
2021-04-08 04:28:29 +08:00
})
2020-11-03 23:13:13 +08:00
```
You can easily bootstrap a new extension via our CLI.
```bash
npm init tiptap-extension
```
2021-05-05 05:59:34 +08:00
Learn [more about custom extensions in our guide](/guide/custom-extensions).