Emoji Hub API Client

A lightweight JavaScript/TypeScript client for the EmojiHub API (https://github.com/cheatsnake/emojihub), providing easy access to emojis by category, group, search, and random selection. This package is ESM-only and works in modern browsers and Node.js 18+ environments that support the Fetch API.

📦 Installation

npm install emoji-hub-api-client

Note: If you are using Node.js, ensure your project supports ES modules.

🎲 Features

1. Lightweight & fast — minimal abstraction over the EmojiHub API
2. Zero dependencies — uses the native fetch API
3. JavaScript & TypeScript support — includes type definitions out of the box
4. Search emojis by name
5. Fetch random emojis
6. Filter emojis by category or group
7. Retrieve all available categories and groups

📚 API Functions

The emoji-hub-api-client package exposes the following functions:

1. getAllEmojiCategories(): Retrieve a list of all available emoji categories.
2. getAllEmojiGroups(): Retrieve a list of all available emoji groups.
3. getAllEmojis(): Fetch all emojis available in the EmojiHub API.
4. getRandomEmoji(): Fetch a single random emoji.
5. getRandomEmojiByCategory(): Fetch a random emoji from a specific category.
6. getRandomEmojiByGroup(): Fetch a random emoji from a specific group.
7. searchEmojisByName(): Search emojis by name.
8. searchSimilarEmojisByName(): Retrieve emojis with names similar to the provided emoji name.

🔤 Example Usage

1. Get All Emoji Categories

import { getAllEmojiCategories } from 'emoji-hub-api-client';

async function run() {
  const response = await getAllEmojiCategories();
  if (response.code === 'api-ok' && response.payload) {
    console.log(response.payload.categories);
  } else {
    console.error('Failed to fetch categories:', response.message);
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": {
    "categories": [
      "smileys and people",
      "animals and nature",
      "food and drink",
      "travel and places"
      ...
      ...
    ]
  }
}
*/

// Error
/*
{
    code: "api-fail",
    message: "Get All Emoji Categories: Encountered Error!",
    payload: null
}
*/

2. Get All Emoji Groups

import { getAllEmojiGroups } from 'emoji-hub-api-client';

async function run() {
  const response = await getAllEmojiGroups();
  if (response.code === 'api-ok' && response.payload) {
    console.log(response.payload.groups);
  } else {
    console.error('Failed to fetch groups:', response.message);
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": {
    "groups": [
      "face positive",
      "face neutral",
      "face negative",
      "animal mammal",
      "animal bird"
      ...
      ...
      ...
    ]
  }
}
*/

// Error
/* { code: "api-fail", message: "Get All Emoji Groups: Encountered Error", payload: null }; */

3. Get All Emojis

import { getAllEmojis } from 'emoji-hub-api-client';

async function run() {
  const response = await getAllEmojis();
  if (response.code === 'api-ok' && response.payload) {
    // Log the first emoji as a sample
    console.log('Sample emoji:', response.payload[0]);
  } else {
    console.error('Failed to fetch emojis:', response.message);
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": [
    {
      "name": "grinning face",
      "category": "smileys and people",
      "group": "face positive",
      "htmlCode": ["😀"],
      "unicode": ["U+1F600"]
    }
    ...
    ...
    ...
  ]
}
*/

// Error
/*
{
    code: "api-fail",
    message: "Get All Emoji: Encountered Error!",
    payload: null
}
*/

4. Get A Random Emoji

import { getRandomEmoji } from 'emoji-hub-api-client';

async function run() {
  const response = await getRandomEmoji();
  if (response.code === 'api-ok' && response.payload) {
    console.log(response.payload);
  } else {
    console.error('Failed to fetch random emoji:', response.message);
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": {
    "name": "rocket",
    "category": "travel and places",
    "group": "transport air",
    "htmlCode": ["🚀"],
    "unicode": ["U+1F680"]
  }
}
*/

// Error
/*
{
    code: "api-fail",
    message: "Get Random Emoji: Encountered Error!",
    payload: null
}
*/

5. Get a Random Emoji by Category

/* Note: To get the type of categories, check the getAllEmojiCategories() function response */
import { getRandomEmojiByCategory } from 'emoji-hub-api-client';

async function run() {
  const response = await getRandomEmojiByCategory({
    category:
      'smileys-and-people' /* join with hyphen if there are more than 2 words */,
  });

  if (response.code === 'api-ok' && response.payload) {
    console.log(response.payload);
  } else {
    console.error(
      'Failed to fetch random emoji by category:',
      response.message,
    );
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": {
    "name": "grinning face",
    "category": "smileys and people",
    "group": "face positive",
    "htmlCode": ["😀"],
    "unicode": ["U+1F600"]
  }
}
*/

// Error
/*
{
    code: "api-fail",
    message: "Get Random Emoji By Category: Encountered Error!",
    payload: null
}
*/

6. Get Random Emoji By Group

/* Note: to get the names of the groups, check the getAllEmojiGroups() function response */
import { getRandomEmojiByGroup } from 'emoji-hub-api-client';

async function run() {
  const response = await getRandomEmojiByGroup({
    group: 'face-positive' /* join with hyphen if there are more than 2 words*/,
  });

  if (response.code === 'api-ok' && response.payload) {
    console.log(response.payload);
  } else {
    console.error('Failed to fetch random emoji by group:', response.message);
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": {
    "name": "smiling face with sunglasses",
    "category": "smileys and people",
    "group": "face positive",
    "htmlCode": ["😎"],
    "unicode": ["U+1F60E"]
  }
}
*/

// Error
/*
{
    code: "api-fail",
    message: "Get Random Emoji By Group: Encountered Error!",
    payload: null
}
*/

7. Search An Emoji By Name/Query

import { searchEmojisByName } from 'emoji-hub-api-client';

async function run() {
  const response = await searchEmojisByName({
    query: 'smile',
  });

  if (response.code === 'api-ok' && response.payload) {
    console.log(`Total results: ${response.payload.totalResults}`);
    console.log(response.payload.results);
  } else {
    console.error('Failed to search emojis:', response.message);
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": {
    "totalResults": 2,
    "results": [
      {
        "name": "smiling face",
        "category": "smileys and people",
        "group": "face positive",
        "htmlCode": ["😊"],
        "unicode": ["U+1F642"]
      },
      {
        "name": "smiling face with sunglasses",
        "category": "smileys and people",
        "group": "face positive",
        "htmlCode": ["😎"],
        "unicode": ["U+1F60E"]
      }
    ]
  }
}
*/

// Error
/*
{
    code: "api-fail",
    message: "Search Emoji(s) By Name: Encountered Error!",
    payload: null
}
*/

8. Get Similar Emoji(s) By Name/Query

import { searchSimilarEmojisByName } from 'emoji-hub-api-client';

async function run() {
  const response = await searchSimilarEmojisByName({
    query: 'heart',
  });
  if (response.code === 'api-ok' && response.payload) {
    console.log(`Total similar emojis found: ${response.payload.totalResults}`);
    console.log(response.payload.results);
  } else {
    console.error('Failed to search similar emojis:', response.message);
  }
}
run();

// 200:OK
/*
{
  "code": "api-ok",
  "message": "No error encountered",
  "payload": {
    "totalResults": 3,
    "results": [
      {
        "name": "red heart",
        "category": "smileys and people",
        "group": "emotion",
        "htmlCode": ["❤"],
        "unicode": ["U+2764"]
      },
      {
        "name": "orange heart",
        "category": "smileys and people",
        "group": "emotion",
        "htmlCode": ["🟧"],
        "unicode": ["U+1F9E7"]
      },
      {
        "name": "yellow heart",
        "category": "smileys and people",
        "group": "emotion",
        "htmlCode": ["💛"],
        "unicode": ["U+1F49B"]
      }
    ]
  }
}
*/

// Error
/*
{
    code: "api-fail",
    message: "Search Similar Emoji(s) By Name: Encountered Error!",
    payload: null
}
*/

📗 Test Coverage

PASS src/get-all-emoji-categories/test/index.test.ts
  Get All Emoji Categories
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the emoji categories endpoint

PASS src/get-random-emoji/test/get-random.test.ts
  Get A Random Emoji
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the random emoji endpoint

PASS src/get-random-emoji/test/get-random-by-group.test.ts
  Get Random Emoji By Group
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the random emoji by group endpoint

PASS src/search-emojis/test/search-similar-emojis-by-name.test.ts
  Search Similar Emojis By Name
    ✓ returns api-fail when query is empty
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the emoji similar search endpoint with encoded query

PASS src/search-emojis/test/search-emojis-by-name.test.ts
  Search Emojis By Name
    ✓ returns api-fail when query is empty
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the emoji search endpoint with encoded query

PASS src/get-all-emojis/test/index.test.ts
  Get All Emojis
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the emoji all endpoint

PASS src/get-all-emoji-groups/test/index.test.ts
  Get All Emoji Groups
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the emoji groups endpoint

PASS src/get-random-emoji/test/get-random-by-category.test.ts
  Get Random Emoji By Category
    ✓ returns api-fail when fetch response is not ok
    ✓ returns payload when response ok
    ✓ targets the random emoji by category endpoint

Test Suites: 8 passed, 8 total
Tests:       26 passed, 26 total
Snapshots:   0 total

-----------------------------------|---------|----------|---------|---------|-------------------
File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-----------------------------------|---------|----------|---------|---------|-------------------
All files                          |     100 |      100 |     100 |     100 |
 get-all-emoji-categories          |     100 |      100 |     100 |     100 |
  index.ts                         |     100 |      100 |     100 |     100 |
 get-all-emoji-groups              |     100 |      100 |     100 |     100 |
  index.ts                         |     100 |      100 |     100 |     100 |
 get-all-emojis                    |     100 |      100 |     100 |     100 |
  index.ts                         |     100 |      100 |     100 |     100 |
 get-random-emoji                  |     100 |      100 |     100 |     100 |
  get-random-by-category.ts        |     100 |      100 |     100 |     100 |
  get-random-by-group.ts           |     100 |      100 |     100 |     100 |
  get-random.ts                    |     100 |      100 |     100 |     100 |
 search-emojis                     |     100 |      100 |     100 |     100 |
  search-emojis-by-name.ts         |     100 |      100 |     100 |     100 |
  search-similar-emojis-by-name.ts |     100 |      100 |     100 |     100 |
 shared                            |     100 |      100 |     100 |     100 |
  index.ts                         |     100 |      100 |     100 |     100 |
-----------------------------------|---------|----------|---------|---------|-------------------

📘 Contributing

Contributions, suggestions, and improvements are welcome. Feel free to open issues or pull requests.

🔒 Security & Privacy

1. This package is open source and intended to provide reusable utilities for application development. It does not collect, store, transmit, sell, or share user data, and it does not include analytics, tracking, telemetry, cookies, local storage usage, backend services, or project-owned data collection mechanisms.
2. For more details, including vulnerability reporting guidance and consumer security recommendations, please see the Security Policy.

❤️ Support

Like this project? Support it with a github star, it would mean a lot to me! Cheers and Happy Coding.