emoji

README

go-emoji

Zero-dependency Go library for emoji lookup and search, backed by an embedded Unicode CLDR dataset. Library only — no CLI. The only external module is testify, used exclusively in tests.

The dataset lives in data/emoji.json (embedded via //go:embed) so emoji updates are data changes, not code changes. Structure inspired by diamondburned/go-emoji.

Install

go get github.com/bobadilla-tech/go-emoji

Usage

package main

import (
	"fmt"

	"github.com/bobadilla-tech/go-emoji"
)

func main() {
	svc := emoji.NewService()

	fmt.Println(svc.GetByName("grinning_face")) // {😀 grinning_face Smileys & Emotion U+1F600} true
	fmt.Println(svc.Random().Emoji)

	results := svc.Search("heart")
	fmt.Printf("%d matches\n", results.Total)

	animals := svc.ByCategory("Animals & Nature")
	fmt.Printf("%d animals\n", animals.Total)

	fmt.Println(svc.Categories())
}

API

• Service.Random() Emoji — random emoji (crypto/rand).
• Service.GetByName(name string) (Emoji, bool) — exact name match, case-insensitive.
• Service.Search(query string) List — case-insensitive substring match on name or category.
• Service.ByCategory(category string) List — case-insensitive exact category match.
• Service.Categories() []string — the distinct categories, in order of first appearance.
• data.RawEmojiJSON []byte — the embedded raw JSON.

Data

data/emoji.json holds 808 records, each with emoji (glyph), name (CLDR snake_case short name), category (Unicode category), and unicode (U+XXXX notation). Derived from the Unicode CLDR / unicode.org emoji specification.

License

MIT. Data derived from the Unicode CLDR emoji specification, which is distributed under the Unicode Terms of Use.

Documentation

Overview

Package emoji provides emoji lookup, search, and category queries backed by the embedded Unicode CLDR emoji dataset.

Index

• type Emoji
• type List
• type Service
  • func NewService() *Service
  • func (s *Service) ByCategory(category string) List
  • func (s *Service) Categories() []string
  • func (s *Service) GetByName(name string) (Emoji, bool)
  • func (s *Service) Random() Emoji
  • func (s *Service) Search(query string) List

Types

type Emoji

type Emoji struct {
	Emoji    string `json:"emoji"`
	Name     string `json:"name"`
	Category string `json:"category"`
	Unicode  string `json:"unicode"`
}

Emoji represents a single emoji with its metadata.

type List

type List struct {
	Items []Emoji `json:"items"`
	Total int     `json:"total"`
}

List represents a collection of emoji search results.

type Service

type Service struct{}

Service provides emoji lookup and search operations.

func NewService

func NewService() *Service

NewService returns a new Service.

func (*Service) ByCategory

func (s *Service) ByCategory(category string) List

ByCategory returns all emojis in the given category (case-insensitive). Returns a List with matching results.

func (*Service) Categories

func (s *Service) Categories() []string

Categories returns the distinct emoji categories in the dataset, in order of first appearance.

func (*Service) GetByName

func (s *Service) GetByName(name string) (Emoji, bool)

GetByName returns the emoji matching the given name (snake_case). Returns the emoji and true if found, or a zero value and false if not.

func (*Service) Random

func (s *Service) Random() Emoji

Random returns a randomly selected emoji using a cryptographically secure random number generator.

func (*Service) Search

func (s *Service) Search(query string) List

Search returns all emojis whose name or category contains the query string (case-insensitive). Returns a List with matching results.