Skip to content

sinansonmez/easy-emojis

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

50 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

easy-emojis

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

npm version npm downloads License

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.

Packages

No packages published

Contributors 2

  •  
  •