A comprehensive TypeScript library for emoji utilities including intelligent text-to-emoji replacement, fast search, flag conversion, and emoji lookup functions.
β¨ Smart Text Replacement β Convert natural language to emojis with contextual awareness
π Emoji Search (new!) β Ranked results with exact/partial matching, category filters, limits
π Emoji Lookup β Find emojis by name, shortname, or get random selections
π³οΈ Flag Conversion β Convert between country codes and flag emojis
π€ Letter Conversion β Transform letters to regional indicator emojis
β‘ High Performance β Optimized algorithms with configurable options
π― TypeScript Support β Full type definitions
# npm
npm install easy-emojis
# yarn
yarn add easy-emojis
# pnpm
pnpm add easy-emojis
import * as EasyEmojis from 'easy-emojis';
// Lookup
EasyEmojis.getEmoji('pizza'); // π
EasyEmojis.getEmoji(':coffee:'); // β
// NEW: Search
EasyEmojis.searchEmojis('apple')[0]?.emoji.emoji; // π (top match)
// Flags & Letters
EasyEmojis.countryCodeToFlag('JP'); // π―π΅
EasyEmojis.letterToEmoji('S'); // πΈ
Ranked search with optional category filtering, strict (exact) mode, and result limits.
import { searchEmojis } from 'easy-emojis';
const results = searchEmojis('apple');
/*
[
{ emoji: { ...π }, score: 100, matchType: 'exact' },
{ emoji: { ...π }, score: 78, matchType: 'partial' },
...
]
*/
// Just the emoji characters:
const chars = results.map(r => r.emoji.emoji); // ["π","π",...]
- Searches match names (e.g.,
"red apple"
) and shortnames (without colons), e.g."apple"
. - Exact matches on name/shortname score 100.
searchEmojis('tada'); // treats shortname; exact if it matches π
searchEmojis('red apple', { exactMatch: true });
// returns only exact name/shortname matches (score = 100)
import { getSearchCategories, searchEmojis } from 'easy-emojis';
const categories = getSearchCategories(); // ["People & Body (family)", "Food & Drink (food-sweet)" ...]
const food = searchEmojis('cake', { category: 'Food & Drink (food-sweet)' });
Tip: Use
getSearchCategories()
to present a category dropdown and pass the selected value tosearchEmojis
.
searchEmojis('face', { limit: 10 });
- Exact match (name or shortname) β
score = 100
,matchType: 'exact'
. - Partial match β
score β [60..90]
, higher if the match occurs earlier in the text.- Name partials are prioritized over shortname partials.
- Secondary sort by shorter name length to bias simpler names when scores tie.
- Empty or whitespaceβonly queries throw:
Error("Search query cannot be empty")
.
import * as EasyEmojis from 'easy-emojis';
// Get random emoji
EasyEmojis.getRandomEmoji(); // e.g. "π"
// Lookup by name or shortname
EasyEmojis.getEmojiByName('red apple'); // "π"
EasyEmojis.getEmojiByShortName(':apple:'); // "π"
// Universal lookup (accepts both)
EasyEmojis.getEmoji('red apple'); // "π"
EasyEmojis.getEmoji(':apple:'); // "π"
import * as EasyEmojis from 'easy-emojis';
EasyEmojis.countryCodeToFlag('US'); // "πΊπΈ"
EasyEmojis.flagToCountryCode('πΊπΈ'); // "US"
EasyEmojis.letterToEmoji('S'); // "πΈ"
EasyEmojis.emojiToLetter('πΈ'); // "S"
Transform your text with intelligent emoji replacements! Perfect for social media, chat apps, and creative content.
import { replaceTextWithEmojis } from 'easy-emojis';
const result = replaceTextWithEmojis("I love pizza and coffee!");
console.log(result.text); // "I β€οΈ π and β!"
import {
replaceTextSubtle, // Conservative
replaceTextBalanced, // Moderate
replaceTextExpressive, // Aggressive
replaceTextSmart // Context-aware
} from 'easy-emojis';
const text = "Having a great morning with coffee and friends!";
replaceTextSubtle(text); // "Having a great morning with β and friends!"
replaceTextBalanced(text); // "Having a great morning with β and friends!"
replaceTextExpressive(text); // "Having a great π
with β and friends!"
replaceTextSmart(text); // Context-aware replacements based on sentiment
import { replaceTextWithEmojis, EmojiReplaceMode } from 'easy-emojis';
const result = replaceTextWithEmojis("I love programming and pizza", {
mode: EmojiReplaceMode.MODERATE,
confidenceThreshold: 0.8,
maxReplacements: 3,
categories: ['food', 'emotion', 'tech'],
customMappings: {
programming: { emoji: 'π»', confidence: 0.9, category: 'tech' }
}
});
console.log(result.text); // "I β€οΈπ» and π"
console.log(result.stats);
// {
// totalReplacements: 3,
// averageConfidence: 0.9,
// categoriesUsed: ['emotion', 'tech', 'food']
// }
Mode | Description | Use Case |
---|---|---|
CONSERVATIVE |
High-confidence, minimal replacements | Professional communication |
MODERATE |
Balanced approach with good coverage | Social media posts |
AGGRESSIVE |
Maximum replacements, lower threshold | Creative content, casual chat |
CONTEXTUAL |
AI-powered context analysis | Smart assistants, adaptive UX |
interface EmojiReplaceOptions {
mode: EmojiReplaceMode;
confidenceThreshold: number;
maxReplacements?: number;
preserveCase?: boolean;
categories?: string[];
customMappings?: object;
}
interface EmojiReplaceResult {
text: string;
replacements: EmojiReplacement[];
originalText: string;
stats: {
totalReplacements: number;
averageConfidence: number;
categoriesUsed: string[];
};
}
Function | Description | Example |
---|---|---|
getRandomEmoji() |
Returns a random emoji | π² |
getEmojiByName(name) |
Find emoji by name | getEmojiByName('pizza') β π |
getEmojiByShortName(shortname) |
Find by shortname | getEmojiByShortName(':pizza:') β π |
getEmoji(query) |
Universal lookup (name or shortname) | getEmoji('pizza') β π |
Function | Description | Example |
---|---|---|
searchEmojis(query, options?) |
Ranked search across names & shortnames | searchEmojis('apple', { limit: 10 }) |
getSearchCategories() |
List available categories (sorted) | getSearchCategories() β string[] |
SearchOptions
type SearchOptions = {
limit?: number; // default 50
category?: string; // exact category string
exactMatch?: boolean; // only exact matches when true
};
SearchResult
type SearchResult = {
emoji: Emoji;
score: number; // 100 exact; 60β90 partial
matchType: 'exact' | 'partial';
};
Function | Description | Example |
---|---|---|
countryCodeToFlag(code) |
Country code β flag | countryCodeToFlag('JP') β π―π΅ |
flagToCountryCode(flag) |
Flag β country code | flagToCountryCode('π―π΅') β JP |
letterToEmoji(letter) |
Letter β regional indicator | letterToEmoji('A') β π¦ |
emojiToLetter(emoji) |
Regional indicator β letter | emojiToLetter('π¦') β A |
Function | Description |
---|---|
replaceTextWithEmojis(text, options) |
Advanced replacement with full control |
replaceTextSubtle(text) |
Conservative preset |
replaceTextBalanced(text) |
Moderate preset |
replaceTextExpressive(text) |
Aggressive preset |
replaceTextSmart(text) |
Context-aware preset |
import { searchEmojis } from 'easy-emojis';
function suggest(query: string) {
if (!query.trim()) return [];
return searchEmojis(query, { limit: 8 }).map(r => ({
char: r.emoji.emoji,
name: r.emoji.name,
shortname: r.emoji.shortname,
score: r.score
}));
}
const post = "Just finished an amazing workout! Time for coffee and relaxation.";
const enhanced = replaceTextBalanced(post);
// "Just finished an amazing workout! Time for β and relaxation."
const message = "Good morning! Having breakfast - eggs and coffee";
const fun = replaceTextExpressive(message);
// "π
! Having breakfast - π₯ and β"
const subject = "Meeting tomorrow - pizza lunch provided";
const professional = replaceTextSubtle(subject);
// "Meeting tomorrow - π lunch provided"
- β‘ Fast: O(N) scoring over the (optionally filtered) dataset, plus a single sort on the result set
- π Memory efficient: Smart data shapes and minimal overhead
- π¦ Lightweight: Tree-shakeable ES modules
- π― Scalable: Handles large texts efficiently
# Clone the repository
git clone https://github.com/sinansonmez/easy-emojis.git
# Install dependencies
npm install
# Run tests
npm run test
# Build the project
npm run build
npm run test
MIT Β© Sinan Chaush
- vNext β Added
searchEmojis()
andgetSearchCategories()
with ranked results, exact/partial matching, category filters, and result limits.