tiptap/docs/api/nodes/mention.md

86 lines
2.3 KiB
Markdown
Raw Normal View History

---
description: Ping all your people @marijn @kevin
2021-10-15 03:20:21 +08:00
icon: at-line
---
2021-01-18 21:39:26 +08:00
# Mention
2021-01-25 17:35:52 +08:00
[![Version](https://img.shields.io/npm/v/@tiptap/extension-mention.svg?label=version)](https://www.npmjs.com/package/@tiptap/extension-mention)
[![Downloads](https://img.shields.io/npm/dm/@tiptap/extension-mention.svg)](https://npmcharts.com/compare/@tiptap/extension-mention?minimal=true)
2021-01-27 18:52:42 +08:00
Honestly, the mention node is amazing. It adds support for `@mentions`, for example to ping users, *and* provides full control over the rendering.
Literally everything can be customized. You can pass a custom component for the rendering. All examples use `.filter()` to search through items, but feel free to send async queries to an API or add a more advanced library like [fuse.js](https://fusejs.io/) to your project.
2021-01-18 21:39:26 +08:00
2020-12-18 00:13:35 +08:00
## Installation
```bash
npm install @tiptap/extension-mention
```
2021-01-26 06:17:02 +08:00
## Dependencies
2021-01-27 18:52:42 +08:00
To place the popups correctly, were using [tippy.js](https://atomiks.github.io/tippyjs/) in all our examples. You are free to bring your own library, but if youre fine with it, just install what we use:
2021-01-26 06:17:02 +08:00
2021-01-27 18:52:42 +08:00
```bash
npm install tippy.js
```
2021-01-26 06:17:02 +08:00
Since 2.0.0-beta.193 we marked the `@tiptap/suggestion` as a peer dependency. That means, you will need to install it manually.
```bash
npm install @tiptap/suggestion
```
2021-01-20 23:56:25 +08:00
## Settings
### HTMLAttributes
Custom HTML attributes that should be added to the rendered HTML tag.
```js
Mention.configure({
HTMLAttributes: {
class: 'my-custom-class',
},
})
```
2023-11-22 06:47:13 +08:00
### renderText
Define how a mention text should be rendered.
2021-10-22 17:18:54 +08:00
```js
Mention.configure({
2023-11-22 06:47:13 +08:00
renderText({ options, node }) {
2021-10-22 17:18:54 +08:00
return `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`
}
})
```
2023-11-22 06:47:13 +08:00
### renderHTML
Define how a mention html element should be rendered, this is useful if you want to render an element other than `span` (e.g `a`)
```js
Mention.configure({
renderHTML({ options, node }) {
return [
"a",
mergeAttributes({ href: '/profile/1' }, options.HTMLAttributes),
2023-11-22 06:47:13 +08:00
`${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`,
];
}
})
```
2021-10-22 17:18:54 +08:00
### suggestion
[Read more](/api/utilities/suggestion)
```js
Mention.configure({
suggestion: {
// …
},
})
```
2021-01-20 23:56:25 +08:00
2020-12-18 00:13:35 +08:00
## Source code
2021-04-21 21:31:11 +08:00
[packages/extension-mention/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-mention/)
2020-12-18 00:13:35 +08:00
## Usage
2021-10-19 00:01:47 +08:00
https://embed.tiptap.dev/preview/Nodes/Mention