Tiptap emoji: keep named inline nodes and their fallback assets readable

An original volunteer journal uses ordinary emoji beside visit notes and a custom observatory symbol beside telescope sessions. The journal must remain understandable when an image fails or a reader copies a note into a plain-text message. Keep “Telescope session” in the sentence; the symbol can accompany that meaning.

Configure the installed extension

For a Tiptap 3 installation, install the documented package through the project's package manager. Add a configured instance to the application's existing extension list:

import Emoji from '@tiptap/extension-emoji';

const journalEmoji = Emoji.configure({
  HTMLAttributes: { class: 'journal-emoji' },
  enableEmoticons: false,
  forceFallbackImages: false
});

Retain the application's base document extensions and content-loading code. The variable configures the feature; it does not create an editor or supply a picker interface.

The two Boolean values above are also the documented defaults. enableEmoticons permits text expressions to become emoji when enabled. Leave it disabled if authors expect expressions such as <3 to remain literal. forceFallbackImages requests image rendering even when a native character could otherwise be used.

The current documentation lists a default Unicode catalog and an extended gitHubEmojis catalog. Choose the catalog intentionally. A larger list changes which entries the integration recognizes; it is not evidence that every device has matching native artwork. The documentation currently says skin tones are not supported, so verify this requirement before adopting the feature for a product that needs them.

Give a custom symbol a stable name

This original catalog entry uses an application-owned fallback asset:

import Emoji, { emojis } from '@tiptap/extension-emoji';

const observatoryEntry = {
  name: 'journal_observatory',
  shortcodes: ['journal_observatory'],
  tags: ['telescope', 'observatory', 'session'],
  group: 'Journal symbols',
  fallbackImage: '/assets/journal/observatory.png'
};

const journalEmojiWithCustomSymbol = Emoji.configure({
  emojis: [...emojis, observatoryEntry]
});

Use this configured instance instead of the earlier one, rather than registering Emoji twice. The asset path is illustrative; the application must provide the real image and have permission to distribute it.

The entry's unique name is stored as a node attribute. Keep it stable when changing search tags or artwork. Renaming it without a compatibility plan can leave older saved nodes referring to a name the new catalog no longer contains.

Custom shortcode input rules and the suggestion interface are separate integration details. If the product exposes a searchable menu, configure the extension's suggestion option and implement its required interface for the installed release. A tags array alone does not build a complete accessible picker.

Check the node, the image and copied text

Use a development journal note containing an ordinary emoji and the custom observatory entry, each beside an explicit sentence. Save through the application's normal JSON or supported HTML route. Reopen with Emoji registered and inspect whether both entries remain recognized.

Then check the reader's actual rendering path. An editor node does not guarantee that a separate static reader understands its representation or loads its fallback assets. Relative image paths also resolve against the reader's location, which can differ from the editor's location. Test the intended address and deployment base path.

Copy the same note into a plain-text field. The extension documents text conversion on copying; examine the actual copied result for your custom entry instead of assuming its image or search tags survive. If the symbol carries information that the copied text loses, keep that information in the surrounding words.

Keep status and identity outside decorative symbols

The TinyMCE emoticons guide describes a different model in which a default picker inserts Unicode text. Tiptap's named inline node adds a catalog and representation decision that must survive save, load and reader rendering.

A completed telescope session still needs an explicit date or completion field if the journal tracks those facts. Changing a symbol should not silently alter that record. Finish by reopening a telescope note, checking its wording and fallback image, and confirming the copied sentence still tells a coordinator what happened.