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.

❤️ Support

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