Registry / serialization / twemoji-parser

twemoji-parser

library14.0.0jsnpmunverified

twemoji-parser is a lightweight JavaScript library developed by Twitter, specifically designed for identifying emoji entities within a given text string. It processes the input and returns an array of structured objects, each describing an identified emoji. These objects include properties such as the emoji's URL (typically pointing to Twemoji assets on a CDN), its `indices` within the original string, the `text` of the emoji itself, and its `type` (always 'emoji'). This library's primary function is to facilitate the rendering of emojis as Twemoji assets, a process that mirrors its internal use within Twitter's own mobile rendering systems. The current stable version is 14.0.0, aligning with the Unicode 14.0 and Emoji 14.0 specifications. While a precise release cadence is not explicitly stated, its official backing and active maintenance by Twitter ensure its ongoing relevance and stability. A key differentiator is its direct integration and compatibility with the broader Twemoji ecosystem, focusing solely on the parsing aspect rather than direct emoji rendering.

serialization

npm install twemoji-parser

package ↗

INSTALL

IMPORT

SIG · TWEMOJI-PARSER

twemoji-parser

serializationjavascriptv14.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'twemoji-parser';

✗ const parse = require('twemoji-parser');

The library primarily uses named exports. Direct CommonJS `require` for `parse` should destructure the export.

parse

✓ import { parse } from 'twemoji-parser';

✗ import parse from 'twemoji-parser';

This library does not use a default export; `parse` is a named export. Importing it as a default will result in `undefined`.

EmojiEntity

✓ import type { EmojiEntity } from 'twemoji-parser';

✗ import { EmojiEntity } from 'twemoji-parser';

For TypeScript users, type imports should use `import type` to avoid bundling unnecessary runtime code, especially if the types are from `@types/twemoji-parser`.

Demonstrates how to import and use the `parse` function to extract emoji entities from a string, including their text, indices, and asset URLs. It also shows a conceptual way to replace them with HTML image tags.

import { parse } from 'twemoji-parser'; const textWithEmojis = 'Hello, world! I love ❤️ and pizza 🍕. What about a party? 🎉'; const entities = parse(textWithEmojis); console.log('Original Text:', textWithEmojis); console.log('Parsed Emoji Entities:'); entities.forEach(entity => { console.log(` - Text: '${entity.text}', Indices: [${entity.indices[0]}, ${entity.indices[1]}], URL: ${entity.url}`); }); // Example of how to (conceptually) replace emojis with img tags let htmlOutput = textWithEmojis; entities.reverse().forEach(entity => { const imgTag = `<img src="${entity.url}" alt="${entity.text}" class="twemoji-emoji" />`; htmlOutput = htmlOutput.substring(0, entity.indices[0]) + imgTag + htmlOutput.substring(entity.indices[1]); }); console.log('\nHTML Output (Conceptual):\n', htmlOutput);

Debug

Known issues

breakingVersion 14.0.0 introduces support for the Emoji 14.0 specification, updating its internal regular expressions and potentially affecting how certain edge-case emoji sequences are parsed or recognized compared to previous versions. While the API remains stable, the parsing behavior for new or complex emoji sets has changed to align with the latest Unicode standard.

fix

Review parsing results for new or complex emoji sequences if upgrading from an older major version. Ensure your Twemoji asset CDN (e.g., twemoji.maxcdn.com) is also serving 14.x assets to match parsing results.

affects: >=14.0.0

gotchaThis library strictly performs string parsing to identify emoji entities and provide their corresponding Twemoji asset URLs. It does not sanitize input or handle rendering, unlike the broader `twemoji` library's DOM parsing methods, which are recommended for security-sensitive rendering scenarios. Using `twemoji-parser`'s output directly in `innerHTML` without proper sanitization can introduce XSS vulnerabilities.

fix

When using `twemoji-parser` to replace emojis with `<img>` tags in HTML, always ensure that the surrounding HTML content is properly sanitized. Consider using DOM manipulation methods (e.g., `document.createElement`) or a secure templating engine, rather than direct `innerHTML` assignments, especially for user-generated content.

affects: >=1.0.0

gotchaThe `url` property returned for each emoji entity often uses a 'v/latest' path segment (e.g., `https://twemoji.maxcdn.com/v/latest/svg/1f9e1.svg`). This means the URL refers to the most current Twemoji assets available on the CDN, which can change without a `twemoji-parser` library update. This dynamic URL might lead to inconsistent asset rendering if the parser's internal emoji definitions get out of sync with the latest CDN assets, or if you rely on fixed asset URLs for caching.

fix

If precise control over Twemoji asset versions is needed for caching or consistency, implement a custom `buildUrl` option in the `parse` function to specify a fixed version number in the asset path (e.g., `v/14.0.0`). Consult the `twemoji` project's CDN documentation for available versioned asset paths.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: parse is not a function

Attempting to import `parse` as a default export (`import parse from 'twemoji-parser';`) or incorrectly destructuring in CommonJS (`const parse = require('twemoji-parser');`).

fix

Use a named import for ESM (`import { parse } from 'twemoji-parser';`) or correctly destructure for CommonJS (`const { parse } = require('twemoji-parser');`).

Emojis are not displaying correctly or are missing, even after parsing.

This library only *parses* emoji entities and provides asset URLs. It does not *render* them. The issue often lies in the subsequent rendering logic (e.g., using the asset URLs in `<img>` tags, or issues with your CDN access or CSS styles).

fix

Ensure you are using the `url` property from the parsed entities to correctly reference Twemoji assets (e.g., `<img src="entity.url" />`). Verify your CDN access (e.g., `twemoji.maxcdn.com`) and that your HTML/CSS allows images to display. Check for network errors loading the emoji images.

Property 'parse' does not exist on type 'typeof import("...")'.

TypeScript error indicating that the `parse` function is not recognized. This typically happens when `@types/twemoji-parser` is not installed or there's a version mismatch between the library and its type definitions.

fix

Install the type definitions: `npm install --save-dev @types/twemoji-parser`. Ensure that the `@types` package version is compatible with your `twemoji-parser` version. You might need to adjust `tsconfig.json` `moduleResolution` if you encounter issues with module detection.

Upgrade

Version history

14.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/twemoji-parser ↗