Tiptap Docs

Create an Emoji Inline Node with Markdown Support

Beta

This guide shows how to add Markdown support for a small atomic inline node that renders emoji shortcodes (for example :smile:). We'll walk through four clear steps and include a full example at each step so you always have the complete context:

  1. Create the basic emoji Node (no Markdown).
  2. Step 2: Add a tokenizer to convert :name: into tokens.
  3. Step 3: Add the parser to turn tokens into Tiptap JSON.
  4. Step 4: Add the renderer to serialize Tiptap JSON back to Markdown.

Example shorthand we'll support:

Hello :smile: world!

Step 1: Create the basic emoji node

Start by defining a small atomic inline node that stores a name attribute and renders an emoji in HTML.

import { Node } from '@tiptap/core'

const emojiMap = {
  smile: '😊',
  heart: '❤️',
  thumbsup: '👍',
  fire: '🔥',
  // add more mappings as needed
}

export const Emoji = Node.create({
  name: 'emoji',

  group: 'inline',
  inline: true,
  atom: true,

  addAttributes() {
    return {
      name: { default: 'smile' },
    }
  },

  parseHTML() {
    return [{ tag: 'span[data-emoji]' }]
  },

  renderHTML({ node }) {
    const emoji = emojiMap[node.attrs.name] || node.attrs.name || 'smile'
    return ['span', { 'data-emoji': node.attrs.name }, emoji]
  },
})

Notes:

  • The node is atom: true and inline so it behaves like an indivisible inline piece of content.
  • emojiMap is used to map short names to actual emoji characters for HTML output.

Step 2: Add a custom Markdown tokenizer

The tokenizer recognizes :name: shortcodes in inline Markdown and returns a token with the emoji name. Below is the full extension including the tokenizer so you can see how it integrates with the base Node.

import { Node } from '@tiptap/core'

const emojiMap = {
  smile: '😊',
  heart: '❤️',
  thumbsup: '👍',
  fire: '🔥',
  // add more mappings as needed
}

export const Emoji = Node.create({
  name: 'emoji',

  group: 'inline',
  inline: true,
  atom: true,

  addAttributes() {
    return {
      name: { default: 'smile' },
    }
  },

  parseHTML() {
    return [{ tag: 'span[data-emoji]' }]
  },

  renderHTML({ node }) {
    const emoji = emojiMap[node.attrs.name] || node.attrs.name || 'smile'
    return ['span', { 'data-emoji': node.attrs.name }, emoji]
  },

  // define a Markdown tokenizer to recognize :name: shortcodes
  markdownTokenizer: {
    name: 'emoji',
    level: 'inline',
    // Fast hint for the lexer
    start: (src) => src.indexOf(':'),
    tokenize: (src, tokens, lexer) => {
      // Match :name: where name can include letters, numbers, underscores, plus signs
      const match = /^:([a-z0-9_+]+):/i.exec(src)
      if (!match) return undefined

      return {
        type: 'emoji',
        raw: match[0],      // full match like ":smile:"
        emojiName: match[1], // captured name like "smile"
      }
    },
  },
})

Implementation notes:

  • start is an optimization used by the lexer to quickly find candidate positions.
  • The tokenizer returns a token object with type, raw, and emojiName fields that the parser will consume.
  • Keep the tokenizer inline-level (level: 'inline') so it integrates with inline parsing.

Step 3: Add the parser

The parseMarkdown function converts the tokenizer token into a Tiptap node. For an atomic inline node, it should return a node object with the type and attrs. Here's the full extension now including tokenizer + parse.

import { Node } from '@tiptap/core'

const emojiMap = {
  smile: '😊',
  heart: '❤️',
  thumbsup: '👍',
  fire: '🔥',
  // add more mappings as needed
}

export const Emoji = Node.create({
  name: 'emoji',

  group: 'inline',
  inline: true,
  atom: true,

  addAttributes() {
    return {
      name: { default: 'smile' },
    }
  },

  parseHTML() {
    return [{ tag: 'span[data-emoji]' }]
  },

  renderHTML({ node }) {
    const emoji = emojiMap[node.attrs.name] || node.attrs.name || 'smile'
    return ['span', { 'data-emoji': node.attrs.name }, emoji]
  },

  markdownTokenizer: {
    name: 'emoji',
    level: 'inline',
    // Fast hint for the lexer
    start: (src) => src.indexOf(':'),
    tokenize: (src, tokens, lexer) => {
      // Match :name: where name can include letters, numbers, underscores, plus signs
      const match = /^:([a-z0-9_+]+):/i.exec(src)
      if (!match) return undefined

      return {
        type: 'emoji',
        raw: match[0],      // full match like ":smile:"
        emojiName: match[1], // captured name like "smile"
      }
    },
  },

  // Parse token into a tiptap node
  parseMarkdown: (token, helpers) => {
    return {
      type: 'emoji',
      attrs: { name: token.emojiName },
    }
  },
})

Notes:

  • The parseMarkdown function should return an object where type matches the node name.
  • Atomic nodes do not supply content; they are standalone nodes with attributes.

Step 4: Add the renderer

To support serializing the editor state back to Markdown shortcodes, implement the renderMarkdown function. It receives a Tiptap node and should return a Markdown string representing that node. Below is the full extension with tokenizer, parse, and render included.

import { Node } from '@tiptap/core'

const emojiMap = {
  smile: '😊',
  heart: '❤️',
  thumbsup: '👍',
  fire: '🔥',
  // add more mappings as needed
}

export const Emoji = Node.create({
  name: 'emoji',

  group: 'inline',
  inline: true,
  atom: true,

  addAttributes() {
    return {
      name: { default: 'smile' },
    }
  },

  parseHTML() {
    return [{ tag: 'span[data-emoji]' }]
  },

  renderHTML({ node }) {
    const emoji = emojiMap[node.attrs.name] || node.attrs.name || 'smile'
    return ['span', { 'data-emoji': node.attrs.name }, emoji]
  },

  markdownTokenizer: {
    name: 'emoji',
    level: 'inline',
    // Fast hint for the lexer
    start: (src) => src.indexOf(':'),
    tokenize: (src, tokens, lexer) => {
      // Match :name: where name can include letters, numbers, underscores, plus signs
      const match = /^:([a-z0-9_+]+):/i.exec(src)
      if (!match) return undefined

      return {
        type: 'emoji',
        raw: match[0],       // full match like ":smile:"
        emojiName: match[1], // captured name like "smile"
      }
    },
  },

  // Parse token into a tiptap node
  parseMarkdown: (token, helpers) => {
    return {
      type: 'emoji',
      attrs: { name: token.emojiName },
    }
  },

  // Render tiptap node back to Markdown
  renderMarkdown: (node, helpers) => {
    // Serialize back to :name: shortcode. Use the stored name attribute.
    return `:${node.attrs?.name || 'unknown'}:`
  },
})

Usage

Set the editor content from Markdown that contains emoji shortcodes. Depending on your Markdown integration, pass contentType: 'markdown' or use the API your setup provides:

editor.commands.setContent('Hello :smile: :heart: :thumbsup:', { contentType: 'markdown' })

This will produce inline emoji nodes with corresponding name attributes, and HTML rendering will display the mapped emoji characters (via emojiMap).

Testing and edge cases

  • Unknown names: If a shortcode isn't in emojiMap, the node currently renders the raw name in the span (you may prefer to show a fallback or remove the node). Validate or normalize names in markdownTokenizer or parseMarkdown if needed.
  • Case sensitivity: The tokenizer uses an i flag to allow case-insensitive names; ensure your emojiMap keys match your chosen convention or normalize them with .toLowerCase().
  • Inline parsing: Because this is an inline tokenizer, it will be tried within paragraph and inline contexts — ensure it doesn't conflict with other inline tokenizers (like emphasis) by adjusting the regex or using surrounding whitespace checks if necessary.
  • Atomic behavior: The node is atomic, so it won't be editable as text. This is appropriate for emoji elements but might need different behavior for editable shortcodes.
PreviouslyCreate a Admonition Extension