data-emoji

Replace :shortcode: text with Unicode emoji characters. Progressive enhancement for any container element — without JS, shortcodes stay as readable text.

Overview

The data-emoji attribute enables automatic replacement of :shortcode: patterns with Unicode emoji characters inside any container element. It scans text nodes using a TreeWalker and performs pure text replacement — no wrapping elements are added.

<p data-emoji>Hello :wave: welcome :rocket:</p>

Attributes

Attribute Values Default Description
data-emoji — — Enables emoji enhancement on the container.
data-emoji-scan once, observe once Scan mode. observe watches for dynamic content changes via MutationObserver.
data-emoji-unknown keep, strip keep How to handle unresolved shortcodes. keep leaves them as-is; strip removes the colon markers.

Block-Level Usage

Apply data-emoji to any container. All text nodes within are scanned, including nested elements. Elements like code, pre, script, style, and textarea are skipped automatically.

<article data-emoji> <h2>Release Notes :tada:</h2> <p>We shipped :rocket: the new feature. Thanks :heart: to all contributors :clap:</p> <p>Bug fixes :wrench: and performance improvements :zap:</p> </article>

Observe Mode

Set data-emoji-scan="observe" to watch for dynamically added or changed content. A MutationObserver watches the subtree and debounces rescans (100ms).

<div data-emoji data-emoji-scan="observe"> <!-- Dynamically added content gets emoji replaced automatically --> </div>

Unknown Shortcodes

By default, unresolved shortcodes are left as-is. Set data-emoji-unknown="strip" to remove the colon markers from unrecognized codes.

<!-- Unresolved shortcodes are removed --> <p data-emoji data-emoji-unknown="strip"> Hello :wave: and :nonexistent_code: world </p> <!-- Renders: Hello 👋 and world -->

Dynamic Content

Elements with data-emoji added to the page after load are automatically enhanced via a global MutationObserver.

// Dynamically added [data-emoji] elements are auto-enhanced const el = document.createElement('p'); el.dataset.emoji = ''; el.textContent = 'Dynamic :fire: content :sparkles:'; document.body.appendChild(el); // Auto-enhanced — no manual init needed

Live Input Replacement

Add data-emoji directly to a <textarea> or <input> to enable live shortcode replacement as the user types. When the closing : completes a valid shortcode, it's instantly replaced with the emoji character.

<textarea data-emoji rows="3" placeholder="Try typing :wave: hello :fire:"></textarea> <input type="text" data-emoji placeholder="Type :heart: here">

Unknown shortcodes are always kept as-is in inputs (the data-emoji-unknown="strip" option only applies to container elements, not inputs — stripping text while typing would be jarring).

Skipped Elements

When data-emoji is on a container, text inside these child elements is never processed:

  • <script>
  • <style>
  • <code>
  • <pre>
  • <textarea> (use data-emoji directly on the textarea for live replacement)
  • Any element with contenteditable

Supported Shortcodes

The core set includes approximately 200 curated emoji across 9 categories: Smileys, People, Animals & Nature, Food & Drink, Travel & Places, Activities, Objects, Symbols, and Flags. Common aliases are supported (e.g., :heart: for :red_heart:, :+1: for :thumbsup:).

See the emoji-picker component for a visual browser of all available emoji. Use data-emoji when users know the shortcode; use emoji-picker when they need to browse and discover. Both share the same dataset and work well together.

Extended Emoji Set

Need the full GitHub/Slack shortcode library? Load the extended emoji file to add ~1,700 more shortcodes (the complete gemoji set). It supplements the core set — no configuration needed.

<!-- Add after vanilla-breeze.js (load order doesn't matter) --> <script type="module" src="/cdn/emoji-extended.js"></script>
Set Shortcodes Size (gzipped) Loaded
Core (default) ~200 Included in main bundle Always
Extended (opt-in) ~1,700 additional ~23 KB Separate script tag