node-emoji

Friendly emoji lookups and parsing utilities for Node.js. 💖

A comprehensive emoji library for Node.js that provides utilities for parsing, searching, and working with emojis. Features both a JavaScript API and a command-line interface.

📦 Installation

For Global CLI Usage

npm

npm install -g @involvex/emoji-cli

yarn

yarn global add @involvex/emoji-cli

pnpm

pnpm add -g @involvex/emoji-cli

bun

bun add -g @involvex/emoji-cli

Without Installation (npx/bunx)

You can also use the CLI without installing it globally:

Using npx (npm)

npx @involvex/emoji-cli --search "heart"
npx @involvex/emoji-cli --get "heart"
npx @involvex/emoji-cli --random

Using bunx (bun)

bunx @involvex/emoji-cli --search "heart"
bunx @involvex/emoji-cli --get "heart"
bunx @involvex/emoji-cli --random

Requirements: Node.js >= 18

🚀 Quick Start

JavaScript API

import { emojify, search, random, get } from '@involvex/emoji-cli'

// Convert text with emoji codes to actual emojis
const text = emojify('I :heart: JavaScript! :tada:')
console.log(text)
// Output: "I ❤️ JavaScript! 🎉"

// Search for emojis by name
const heartEmojis = search('heart')
console.log(heartEmojis)
// Output: [{ emoji: '❤️', name: 'heart' }, { emoji: '💔', name: 'broken_heart' }, ...]

// Get a specific emoji
const heart = get('heart')
console.log(heart)
// Output: '❤️'

// Get a random emoji
const randomEmoji = random()
console.log(randomEmoji)
// Output: { emoji: '🌈', name: 'rainbow' }

Command Line Interface

After installation, you can use the emoji-cli command:

# Search for emojis
emoji-cli --search "heart"

# Get a specific emoji
emoji-cli --get "heart"

# Convert text to emojis
emoji-cli --emojify "I love JavaScript!"

# Convert emojis back to text
emoji-cli --unemojify "I ❤️ JavaScript!"

# Get a random emoji
emoji-cli --random

# Check if an emoji exists
emoji-cli --has "heart"

✨ Features

• 🔍 Powerful Search: Search emojis by name, keyword, or pattern matching
• 📝 Text Conversion: Convert between text with emoji codes and actual emojis
• 🎲 Random Selection: Get random emojis for variety and fun
• 🔧 Utility Functions: Comprehensive set of emoji manipulation utilities
• 🖥️ CLI Interface: Command-line tool for emoji operations
• 📦 Tree Shaking: Modern ESM module support for better bundling
• 🧪 Well Tested: Comprehensive test coverage with Vitest
• ⚡ TypeScript: Full TypeScript support with proper type definitions

📖 API Documentation

Core Functions

emojify(input, options)

Parse markdown-encoded emojis in a string and convert them to actual emoji characters.

Parameters:

• input (string): The text containing emoji codes like :heart:
• options (object, optional):
  • fallback (string | function): Fallback for unknown emoji codes
  • format (function): Custom formatting function for matched emojis

Returns: string

Examples:

import { emojify } from '@involvex/emoji-cli'

emojify('Hello :world:!')
// Output: "Hello 🌍!"

// With custom fallback
emojify('I :unknown: this', { fallback: '❓' })
// Output: "I ❓ this"

// With custom format function
emojify('I :heart: this', {
  format: (emoji, code) => `${emoji} (${code})`,
})
// Output: "I ❤️ (:heart:) this"

search(keyword)

Search for emojis by name or pattern.

Parameters:

• keyword (string | RegExp): Search term or regular expression

Returns: Array of { emoji, name } objects

Examples:

import { search } from '@involvex/emoji-cli'

search('heart')
// Output: [{ emoji: '❤️', name: 'heart' }, { emoji: '💔', name: 'broken_heart' }]

search(/^heart/)
// Output: All emojis starting with "heart"

search('face')
// Output: All emojis containing "face" in their name

get(codeOrName)

Get an emoji by its code or name.

Parameters:

• codeOrName (string): Emoji code (e.g., 'heart') or emoji character

Returns: string | undefined

Examples:

import { get } from '@involvex/emoji-cli'

get('heart')
// Output: '❤️'

get('❤️')
// Output: '❤️'

get('non-existent')
// Output: undefined

random()

Get a random emoji.

Returns: { emoji, name } object

Examples:

import { random } from '@involvex/emoji-cli'

random()
// Output: { emoji: '🌈', name: 'rainbow' }

replace(input, replacement, options)

Replace emojis in a string with custom replacements.

Parameters:

• input (string): Input text containing emojis
• replacement (string | function): Replacement text or function
• options (object, optional):
  • preserveSpaces (boolean): Whether to preserve spaces after emojis

Returns: string

Examples:

import { replace } from '@involvex/emoji-cli'

replace('I ❤️ JavaScript!', '[EMOJI]')
// Output: "I [EMOJI] JavaScript!"

replace('I ❤️ JavaScript!', (emoji, index) => `[${emoji.name}]`)
// Output: "I [heart] JavaScript!"

strip(input)

Remove all emojis from a string.

Parameters:

• input (string): Input text

Returns: string

Examples:

import { strip } from '@involvex/emoji-cli'

strip('I ❤️ JavaScript! 🎉')
// Output: "I JavaScript!"

unemojify(input)

Convert emojis back to their markdown codes.

Parameters:

• input (string): Input text containing emojis

Returns: string

Examples:

import { unemojify } from '@involvex/emoji-cli'

unemojify('I ❤️ JavaScript!')
// Output: "I :heart: JavaScript!"

which(emoji, options)

Get the name/code of an emoji.

Parameters:

• emoji (string): The emoji character
• options (object, optional):
  • markdown (boolean): Return in markdown format

Returns: string | undefined

Examples:

import { which } from '@involvex/emoji-cli'

which('❤️')
// Output: 'heart'

which('❤️', { markdown: true })
// Output: ':heart:'

find(codeOrName)

Find an emoji by code or name, returning both emoji and name.

Parameters:

• codeOrName (string): Emoji code or name

Returns: { emoji, name } | undefined

Examples:

import { find } from '@involvex/emoji-cli'

find('heart')
// Output: { emoji: '❤️', name: 'heart' }

find('❤️')
// Output: { emoji: '❤️', name: 'heart' }

has(codeOrName)

Check if an emoji exists.

Parameters:

• codeOrName (string): Emoji code or name

Returns: boolean

Examples:

import { has } from '@involvex/emoji-cli'

has('heart')
// Output: true

has('non-existent')
// Output: false

🛠️ Configuration

Node.js Requirements

• Node.js: >= 18.0.0
• Package Manager: npm, yarn, pnpm, or bun

TypeScript Support

The package includes full TypeScript definitions. No additional types package needed:

import { emojify, search, type EmojifyOptions } from '@involvex/emoji-cli'

const options: EmojifyOptions = {
  fallback: '❓',
  format: (emoji, name) => `${emoji} (${name})`,
}

const result = emojify('Hello :world:!', options)

🐛 Troubleshooting

Common Issues

"Cannot find module '@involvex/emoji-cli'"

• Ensure you have Node.js >= 18 installed
• Try reinstalling: npm install @involvex/emoji-cli
• Check that your package manager is up to date

"Unknown command" in CLI

• For global CLI usage: Ensure you've installed the package globally with your package manager
• Try without installation: npx @involvex/emoji-cli --help or bunx @involvex/emoji-cli --help
• For npm global install: npm install -g @involvex/emoji-cli
• For yarn global install: yarn global add @involvex/emoji-cli
• For pnpm global install: pnpm add -g @involvex/emoji-cli
• For bun global install: bun add -g @involvex/emoji-cli
• Check that the emoji name/code exists using search()

"Emoji not found"

• Verify the emoji name using search() function
• Some emojis may not be available in all fonts/platforms
• Check for typos in emoji names

Getting Help

• 📋 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: This README and inline code documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Clone the repository

   git clone https://github.com/involvex/node-emoji.git
   cd node-emoji

2. Install dependencies

   npm install

3. Run tests

   npm test

4. Build the project

   npm run build

5. Run linting

   npm run lint

Contribution Guidelines

• Follow the existing code style and conventions
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PRs
• Use conventional commit messages

Adding New Emojis

Emojis are sourced from the emojilib package. To request new emojis, please contribute to that project.

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🙏 Acknowledgments

• Emoji Data: emojilib - Comprehensive emoji database
• Inspiration: Built upon the original node-emoji by Daniel Biedermann
• Community: Thanks to all contributors and users who make this project better

📊 Package Information

Keywords

emoji, simple, emoticons, emoticon, emojis, smiley, smileys, smilies, ideogram, ideograms

Engines

• Node.js: >= 18

Dependencies

• @sindresorhus/is: Type checking and validation utilities
• char-regex: Character matching utilities
• emojilib: Emoji database and utilities
• jiti: JavaScript Runtime detection
• skin-tone: Skin tone variation support

Dev Dependencies

• TypeScript: Static type checking
• Vitest: Testing framework
• ESLint: Code linting
• Prettier: Code formatting
• tsup: Build tooling

Made with 💖 by Involvex

⭐ Star this project on GitHub if you find it helpful!