node-emojis

node-emojis

A modern, tree-shakeable emoji library for Node.js and browsers with TypeScript support.

Features

• Tree-shakeable - Import only what you need
• 360+ emojis from Unicode 1.0 to 15.0
• Smart search with keyword matching
• Skin tone support for 150+ human emojis
• Emoji aliases (thumbsup/+1/thumbs_up)
• TypeScript support with full type definitions
• Zero dependencies
• Optimized for performance

Requirements

• Node.js 20.0.0 or higher
• TypeScript 5.0+ (for TypeScript users)

Installation

npm install node-emojis

Quick Start

// Import everything (backward compatible)
const emojis = require('node-emojis')
console.log(emojis.fire) // 🔥

// Import only what you need (recommended)
const { search } = require('node-emojis/search')
const { applySkinTone } = require('node-emojis/skin-tones')

ES Modules

import emojis from 'node-emojis'
import { search } from 'node-emojis/search'
import { applySkinTone } from 'node-emojis/skin-tones'

API

Basic Usage

const emojis = require('node-emojis')

// Access emojis directly
emojis.fire        // 🔥
emojis.pizza       // 🍕
emojis.unicorn     // 🦄
emojis['+1']       // 👍 (alias support)

Search

const { search, getByCategory } = require('node-emojis/search')

// Search by keyword
const results = search('happy')
// Returns: [{ name: 'smile', emoji: '😊', keywords: [...], score: 0.8 }, ...]

// Get all emojis in a category
const animals = getByCategory('animals')
// Returns: [{ name: 'dog', emoji: '🐕', ... }, ...]

Skin Tones

const { applySkinTone, supportsSkinTone, getAllSkinToneVariations } = require('node-emojis/skin-tones')

// Apply skin tone
applySkinTone('👋', 'medium')     // 👋🏽
applySkinTone('👋', '3')          // 👋🏽 (Fitzpatrick scale)

// Check if emoji supports skin tones
supportsSkinTone('wave')          // true
supportsSkinTone('fire')          // false

// Get all variations
getAllSkinToneVariations('👋')
// { light: '👋🏻', 'medium-light': '👋🏼', medium: '👋🏽', ... }

Aliases

const { getAliases, getPrimaryName, isSameEmoji } = require('node-emojis/aliases')

// Get aliases
getAliases('fire')                // ['flame', 'hot', 'lit', 'snapstreak']

// Get primary name
getPrimaryName('+1')              // 'thumbs_up'

// Check if two names refer to the same emoji
isSameEmoji('thumbsup', '+1')     // true

Filters

const { filterByCategory, filterByVersion, filterByKeyword } = require('node-emojis/filters')

// Filter by category
const foods = filterByCategory('food')

// Filter by Unicode version
const modernEmojis = filterByVersion('10.0', 'min')  // Unicode 10.0+
const oldEmojis = filterByVersion('1.0', 'exact')    // Only Unicode 1.0

// Filter by keyword
const hearts = filterByKeyword('heart')

Utilities

const { getNameFromEmoji, isValidEmoji, isValidEmojiName } = require('node-emojis')

// Reverse lookup
getNameFromEmoji('🔥')            // 'fire'

// Validation
isValidEmoji('🔥')                // true
isValidEmojiName('fire')          // true

Tree Shaking

Import only what you need to minimize bundle size:

// ❌ Imports entire library
import emojis from 'node-emojis'

// ✅ Imports only search functionality
import { search } from 'node-emojis/search'

// ✅ Import multiple features
import { search } from 'node-emojis/search'
import { applySkinTone } from 'node-emojis/skin-tones'
import { getAliases } from 'node-emojis/aliases'

Bundle Size Comparison

Import Style	Size (minified)
Full library	~85KB
Search only	~15KB
Skin tones only	~8KB
Aliases only	~6KB
Direct data import	~60KB

Documentation

For comprehensive documentation, examples, and guides:

• Complete Documentation - All guides and references
• Getting Started - Installation and basic usage
• API Reference - Complete API documentation
• FAQ - Frequently asked questions
• Migration Guide - Upgrading from v0.x
• GitHub Wiki - Online documentation

Examples

See the examples directory for more usage examples:

• Basic usage - CommonJS examples
• Modern usage - Tree-shaking examples

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

We use Conventional Commits for commit messages.

License

MIT Jesse Palmer

Acknowledgments

Emoji data sourced from Unicode.org and Emojipedia.