easy-emojis

A comprehensive TypeScript library for emoji utilities including intelligent text-to-emoji replacement, fast search, flag conversion, and emoji lookup functions.

Features

✨ 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

Installation

# npm
npm install easy-emojis

# yarn
yarn add easy-emojis

# pnpm
pnpm add easy-emojis

Quick Start

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');       // 🇸

---

🔎 New: Emoji Search

Ranked search with optional category filtering, strict (exact) mode, and result limits.

Basic Usage

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); // ["🍎","🍏",...]

Shortnames & Names

• 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 🎉

Exact Match Mode

searchEmojis('red apple', { exactMatch: true });
// returns only exact name/shortname matches (score = 100)

Category Filtering

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 to searchEmojis.

Limiting Results

searchEmojis('face', { limit: 10 });

Scoring & Sorting (How results are ranked)

• 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.

Error Handling

• Empty or whitespace‐only queries throw: Error("Search query cannot be empty").

---

Emoji Lookup

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:');   // "🍎"

---

Flag & Letter Conversion

import * as EasyEmojis from 'easy-emojis';

EasyEmojis.countryCodeToFlag('US'); // "🇺🇸"
EasyEmojis.flagToCountryCode('🇺🇸'); // "US"

EasyEmojis.letterToEmoji('S'); // "🇸"
EasyEmojis.emojiToLetter('🇸'); // "S"

---

🚀 Smart Text Replacement

Transform your text with intelligent emoji replacements! Perfect for social media, chat apps, and creative content.

Basic Usage

import { replaceTextWithEmojis } from 'easy-emojis';

const result = replaceTextWithEmojis("I love pizza and coffee!");
console.log(result.text); // "I ❤️ 🍕 and ☕!"

Replacement Presets

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

Advanced Configuration

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']
// }

Replacement Modes Explained

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

Configuration Options

interface EmojiReplaceOptions {
  mode: EmojiReplaceMode;
  confidenceThreshold: number;
  maxReplacements?: number;
  preserveCase?: boolean;
  categories?: string[];
  customMappings?: object;
}

Return Value

interface EmojiReplaceResult {
  text: string;
  replacements: EmojiReplacement[];
  originalText: string;
  stats: {
    totalReplacements: number;
    averageConfidence: number;
    categoriesUsed: string[];
  };
}

---

API Reference

Core

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') → 🍕

Search (new)

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';
};

Conversion

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

Text Replacement

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

---

Real-World Examples

Typeahead / Autocomplete with Search

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
  }));
}

Social Media Enhancement

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."

Chat Application

const message = "Good morning! Having breakfast - eggs and coffee";
const fun = replaceTextExpressive(message);
// "🌅! Having breakfast - 🥚 and ☕"

Email Subject Lines

const subject = "Meeting tomorrow - pizza lunch provided";
const professional = replaceTextSubtle(subject);
// "Meeting tomorrow - 🍕 lunch provided"

---

Performance

• ⚡ 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

---

Development Setup

# 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

Running Tests

npm run test

---

License

MIT © Sinan Chaush

---

Changelog

• vNext – Added searchEmojis() and getSearchCategories() with ranked results, exact/partial matching, category filters, and result limits.