gomoji

README

GoMoji 🔥

GoMoji makes it easy to detect, remove, replace, and look up emojis in Go strings.

It solves the common problem that emojis aren't always a single "character"—GoMoji handles them correctly so your string logic just works.

Table of Contents

• Installation
• Quick Start
• Features
• Usage Examples
  • Check for Emojis
  • Find All Emojis
  • Remove Emojis
  • Replace Emojis
  • Get Emoji Information
• API Documentation
• Automated Updates
• Performance
• Security
• Feedback
• Contributing
• License

Installation

Prerequisites

• Go 1.11 or higher (for module support)

Installing

go get -u github.com/forPelevin/gomoji

Quick Start

Create a minimal program that detects and removes emojis:

package main

import (
    "fmt"
    "github.com/forPelevin/gomoji"
)

func main() {
    s := "Hello 👋 world 🦋"
    fmt.Println(gomoji.ContainsEmoji(s)) // true
    fmt.Println(gomoji.RemoveEmojis(s))  // "Hello  world "
}

Then run:

go mod init example.com/hello
go get github.com/forPelevin/gomoji@latest
go run .

Features

• 🔎 Fast emoji detection in strings
• 👪 Find all emoji occurrences with detailed information
• 🌐 Access comprehensive emoji database
• 🧹 Remove emojis from strings
• ↔️ Replace emojis with custom characters
• ↕️ Custom emoji replacement functions
• 🧐 Detailed emoji information lookup
• 🔄 Automated Unicode updates via gomoji-updater

Usage Examples

Check for Emojis

package main

import "github.com/forPelevin/gomoji"

func main() {
    hasEmoji := gomoji.ContainsEmoji("hello world 🤗")
    println(hasEmoji) // true
}

Find All Emojis

emojis := gomoji.FindAll("🧖 hello 🦋 world")
// Returns slice of Emoji structs with detailed information

Remove Emojis

cleaned := gomoji.RemoveEmojis("🧖 hello 🦋 world")
println(cleaned) // "hello world"

Replace Emojis

// Replace with a specific character
replaced := gomoji.ReplaceEmojisWith("🧖 hello 🦋 world", '_')
println(replaced) // "_ hello _ world"

// Replace with custom function
customReplaced := gomoji.ReplaceEmojisWithFunc("🧖 hello 🦋 world", func(em Emoji) string {
    return em.Slug
})
println(customReplaced) // "person-in-steamy-room hello butterfly world"

Get Emoji Information

info, err := gomoji.GetInfo("🦋")
if err == nil {
    println(info.Slug)        // "butterfly"
    println(info.UnicodeName) // "E3.0 butterfly"
    println(info.Group)       // "Animals & Nature"
}

API Documentation

Emoji Structure

type Emoji struct {
    Slug        string `json:"slug"`        // Unique identifier
    Character   string `json:"character"`   // The emoji character
    UnicodeName string `json:"unicode_name"` // Official Unicode name
    CodePoint   string `json:"code_point"`  // Unicode code point
    Group       string `json:"group"`       // Emoji group category
    SubGroup    string `json:"sub_group"`   // Emoji subgroup category
}

Core Functions

• ContainsEmoji(s string) bool - Checks if a string contains any emoji
• FindAll(s string) []Emoji - Finds all unique emojis in a string
• CollectAll(s string) []Emoji - Finds all emojis including repeats (preserves order)
• RemoveEmojis(s string) string - Removes all emojis from a string
• ReplaceEmojisWith(s string, c rune) string - Replaces emojis with a specified character
• ReplaceEmojisWithSlug(s string) string - Replaces emojis with their slugs
• ReplaceEmojisWithFunc(s string, replacer func(Emoji) string) string - Replaces emojis via a custom function
• GetInfo(emoji string) (Emoji, error) - Gets detailed information about an emoji; returns ErrStrNotEmoji if not found
• AllEmojis() []Emoji - Returns all available emojis

For full reference documentation generated from source, see the package docs on pkg.go.dev: github.com/forPelevin/gomoji.

Automated Updates

GoMoji automatically stays up-to-date with the latest Unicode emoji standards through our automated update system:

• Daily Updates: Our GitHub Actions workflow runs daily to check for new Unicode emoji releases
• Automated PRs: When new emoji data is available, automated pull requests are created for review
• Source: Emoji data is fetched from the official Unicode Consortium: https://unicode.org/Public/emoji/latest/
• Tool: Updates are generated using gomoji-updater, a specialized tool for processing Unicode emoji data

Performance

GoMoji is designed for high performance, with parallel processing capabilities for optimal speed. Here are the key benchmarks:

Operation	Sequential Performance	Parallel Performance	Allocations
Contains Emoji	57.49 ns/op	7.167 ns/op	0 B/op, 0 allocs/op
Remove Emojis	1454 ns/op	201.4 ns/op	68 B/op, 2 allocs/op
Find All	1494 ns/op	313.8 ns/op	288 B/op, 2 allocs/op
Get Info	8.591 ns/op	1.139 ns/op	0 B/op, 0 allocs/op
Replace With Slug	3822 ns/op	602.4 ns/op	160 B/op, 3 allocs/op

Full benchmark details:

go test -bench=. -benchmem -v -run Benchmark ./...
goos: darwin
goarch: arm64
pkg: github.com/forPelevin/gomoji
cpu: Apple M1 Pro
BenchmarkContainsEmojiParallel-10               164229604                7.167 ns/op           0 B/op             0 allocs/op
BenchmarkContainsEmoji-10                       20967183                57.49 ns/op            0 B/op             0 allocs/op
BenchmarkReplaceEmojisWithSlugParallel-10        2160638               602.4 ns/op           160 B/op             3 allocs/op
BenchmarkReplaceEmojisWithSlug-10                 309879              3822 ns/op             160 B/op             3 allocs/op
BenchmarkRemoveEmojisParallel-10                 5794255               201.4 ns/op            68 B/op             2 allocs/op
BenchmarkRemoveEmojis-10                          830334              1454 ns/op              68 B/op             2 allocs/op
BenchmarkGetInfoParallel-10                     989043939                1.139 ns/op           0 B/op             0 allocs/op
BenchmarkGetInfo-10                             139558108                8.591 ns/op           0 B/op             0 allocs/op
BenchmarkFindAllParallel-10                      4029028               313.8 ns/op           288 B/op             2 allocs/op
BenchmarkFindAll-10                               751990              1494 ns/op             288 B/op             2 allocs/op

Note: Benchmarks were performed on Apple M1 Pro processor. Your results may vary depending on hardware.

Security

• This is a string-processing library, not a general-purpose sanitizer. Do not rely on it to prevent XSS or other injection attacks; use a proper HTML/markup sanitizer where needed.
• Emoji detection and replacement operate on Unicode grapheme clusters. Do not assume 1 code point == 1 visible symbol.
• Variation selectors are stripped during processing to normalize output. If your application depends on preserving exact variation selectors, avoid RemoveEmojis/Replace* or handle this explicitly.
• When replacing with slugs, treat the resulting text as untrusted like any other user-controlled string and escape/encode as appropriate for the output context.
• If you need normalization against visually confusable characters, use additional tooling (e.g., golang.org/x/text packages) alongside this library.

Feedback

• Bug report: please open an issue with a minimal repro and environment details.
• Feature request: suggest an enhancement describing the use case and expected behavior.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Requirements

• Follow Go’s style guidelines:
  • Effective Go
  • Go Code Review Comments
• Keep code formatted and linted: run make lint-fix (uses goimports, gofmt, and golangci-lint).
• Add tests for new functionality and fixes; all tests must pass: make test or go test ./....
• For performance-sensitive changes, include relevant benchmarks or comparisons (make bench).

How to contribute

1. Fork the repo and create a feature branch.
2. Make your changes, run linters and tests locally.
3. Open a PR describing the change and linking any related issue: open a pull request.

Contact

Vlad Gukasov

License

GoMoji is available under the MIT License. GoMoji source code is available under the MIT License.

Documentation

Index

• Variables
• func ContainsEmoji(s string) bool
• func RemoveEmojis(s string) string
• func ReplaceEmojisWith(s string, c rune) string
• func ReplaceEmojisWithFunc(s string, replacer replacerFn) string
• func ReplaceEmojisWithSlug(s string) string
• type Emoji
  • func AllEmojis() []Emoji
  • func CollectAll(s string) []Emoji
  • func FindAll(s string) []Emoji
  • func GetInfo(emoji string) (Emoji, error)

Variables

var (
	ErrStrNotEmoji = errors.New("the string is not emoji")
)

errors

Functions

func ContainsEmoji

func ContainsEmoji(s string) bool

ContainsEmoji checks whether given string contains emoji or not. It uses local emoji list as provider.

func RemoveEmojis

func RemoveEmojis(s string) string

RemoveEmojis removes all emojis from the s string and returns a new string.

func ReplaceEmojisWith

func ReplaceEmojisWith(s string, c rune) string

ReplaceEmojisWith replaces all emojis from the s string with the specified rune and returns a new string.

func ReplaceEmojisWithFunc

func ReplaceEmojisWithFunc(s string, replacer replacerFn) string

ReplaceEmojisWithFunc replaces all emojis from the s string with the result of the replacerFn function and returns a new string.

func ReplaceEmojisWithSlug

func ReplaceEmojisWithSlug(s string) string

ReplaceEmojisWithSlug replaces all emojis from the s string with the emoji's slug and returns a new string.

Types

type Emoji

type Emoji struct {
	Slug        string `json:"slug"`
	Character   string `json:"character"`
	UnicodeName string `json:"unicode_name"`
	CodePoint   string `json:"code_point"`
	Group       string `json:"group"`
	SubGroup    string `json:"sub_group"`
}

Emoji is an entity that represents comprehensive emoji info.

func AllEmojis

func AllEmojis() []Emoji

AllEmojis gets all emojis from provider.

func CollectAll

func CollectAll(s string) []Emoji

CollectAll finds all emojis in given string. Unlike FindAll, this does not distinct repeating occurrences of emoji. If there are no emojis it returns a nil-slice.

func FindAll

func FindAll(s string) []Emoji

FindAll finds all emojis in given string. If there are no emojis it returns a nil-slice.

func GetInfo

func GetInfo(emoji string) (Emoji, error)

GetInfo returns a gomoji.Emoji model representation of provided emoji. If the emoji was not found, it returns the gomoji.ErrStrNotEmoji error