@usespaceui/emoji

v0.1.0

Published

4 days ago

A modern, unified emoji library for React featuring Apple, Fluent (Microsoft), Telegram, Twemoji, Blobmoji, and Google Noto emojis.

0High
0Medium
0Low

redoragoooo

emoji fluent-emoji apple-emoji telegram-emoji twemoji blobmoji noto-emoji react spaceui icons

✨ Overview

@usespaceui/emoji is a unified, accessible, and lightweight emoji library for React and headless JavaScript/TypeScript runtimes. Render high-resolution 3D, animated, vector, or retro emojis across top design ecosystems with zero configuration.

6 Design Providers: Microsoft Fluent, Apple, Telegram, Google Noto, Twemoji (Twitter/X), and Google Blobmoji.
Multiple Visual Styles: 3D, Animated, Flat (Vector), Modern, Mono, and Native Pure OS text.
Direct Multi-Format Media: WebP (Fluent/Telegram anim), PNG (still), SVG, GIF, AVIF, and Lottie JSON (Noto).
Opt-in fallback: fallback is off by default. Missing assets render nothing. Pass fallback to cascade to another pack or native text.
Typed catalogs: generated EmojiCatalog types per provider/style from CDN filenames.
Headless & SSR Compatible: Core resolvers have zero React dependencies and run anywhere (Node.js, Next.js Edge, Bun, Cloudflare Workers).

🎨 Provider Matrix

📦 Installation

pnpm add @usespaceui/emoji
# or
npm install @usespaceui/emoji
# or
yarn add @usespaceui/emoji

🚀 Usage

1. React Component (`@usespaceui/emoji/react`)

import { Emoji } from '@usespaceui/emoji/react'

export default function App() {
  return (
    <div className="flex items-center gap-4">
      {/* Microsoft Fluent 3D (default) */}
      <Emoji emoji="🔥" type="3d" size={48} />

      {/* Microsoft Fluent animation (WebP). PNG in anim/ is a still, not APNG. */}
      <Emoji emoji="🚀" source="fluent" type="anim" format="webp" size={48} />

      {/* Apple Standard (iOS / macOS PNG) */}
      <Emoji emoji="🍎" source="apple" size={48} />

      {/* Telegram HD Animated WebP (512x512) */}
      <Emoji emoji="🎉" source="telegram" type="anim" size={48} />

      {/* Google Noto Live from Google Fonts (WebP, GIF, Lottie, SVG) */}
      <Emoji emoji="🤖" source="noto" type="anim" format="gif" size={48} />

      {/* Twemoji Scalable Vector (SVG) */}
      <Emoji emoji="✨" source="twemoji" size={48} />

      {/* Classic Google Blobs (Blobmoji) */}
      <Emoji emoji="🫠" source="blobmoji" size={48} />

      {/* Pure Native Text Rendering (OS System Font) */}
      <Emoji emoji="💎" type="pure" size={40} />
    </div>
  )
}

2. Smart Fallback Cascade

fallback defaults to false: missing assets render null (no native glyph, no hex). Opt in to cascade:

// 🪨 (Rock) does not exist in Telegram Anim:
// With fallback enabled, it automatically falls back to Fluent Anim WebP!
<Emoji
  emoji="🪨"
  source="telegram"
  type="anim"
  fallback
  size={48}
/>

// Or specify an explicit fallback provider target:
<Emoji
  emoji="🪨"
  source="telegram"
  fallback="apple"
  size={48}
/>

3. React Hook (`useEmoji`)

import { useEmoji } from '@usespaceui/emoji/react'

function EmojiAvatar({ emoji }: { emoji: string }) {
  const { url, isNative } = useEmoji(emoji, {
    source: 'fluent',
    type: '3d',
  })

  if (isNative) {
    return <span>{emoji}</span>
  }

  return <img src={url} alt={emoji} className="w-10 h-10" />
}

🧠 Headless Core API (`@usespaceui/emoji`)

The root entry point is 100% headless with zero React dependencies, suitable for Node.js, Next.js Server Components, API routes, or any backend:

import {
  resolveEmojiUrl,
  getEmojiUrls,
  getGoogleNotoUrl,
  isEmojiSupported,
  getSmartFallbackForEmoji,
  getAvailableProvidersForEmoji,
  extractEmoji,
  getEmojiName,
  getEmoji,
  toUnicode,
  fromUnicode,
  listSupportedEmojis,
} from '@usespaceui/emoji'

// 1. Resolve Primary CDN Asset URL
const url = resolveEmojiUrl('🔥', { source: 'fluent', type: '3d' })
// -> "https://cdn.spaceui.one/common/emoji/fluent/3d/1f525.webp"

// 2. Resolve Multi-CDN Redundancy Mirrors
const mirrors = getEmojiUrls('🔥', { source: 'fluent', type: '3d' })
// -> ["https://cdn.spaceui.one/...", "https://cdn.aurthle.com/..."]

// 3. Resolve Direct Google Fonts CDN URL for Google Noto
const notoUrl = getGoogleNotoUrl('🤖', 'webp')
// -> "https://fonts.gstatic.com/s/e/notoemoji/latest/1f916/512.webp"

// 4. Inspect Asset Availability in Manifest (pass format to check the real file)
isEmojiSupported('🔥', { source: 'telegram', type: 'anim' }) // true
isEmojiSupported('1f170', { source: 'fluent', type: 'anim', format: 'webp' }) // false (png only)
isEmojiSupported('🪨', { source: 'telegram', type: 'anim' }) // false

// 5. Query All Providers Supporting an Emoji
const providers = getAvailableProvidersForEmoji('🪨')
// -> [{ source: "apple", type: "flat" }, { source: "fluent", type: "3d" }, ...]

// 6. List filenames that actually exist for a pack/format
listSupportedEmojis('fluent', 'anim', 'webp') // ["0023-fe0f", "1f600", ...]

// 7. Unicode & Name Utilities
const char = extractEmoji('Rocket 🚀 launch') // "🚀"
const name = getEmojiName('🤯') // "exploding-head"
const glyph = getEmoji('exploding-head') // "🤯"
const hex = toUnicode('😀') // "1f600"
const back = fromUnicode('1f600') // "😀"

const fallbackTarget = getSmartFallbackForEmoji('🪨', 'telegram', 'anim')
// -> { source: "fluent", type: "anim" }

⚙️ Props & Options Reference (`<Emoji />`)

| Prop | Type | Default | Description | | :------------ | :----------------------------------------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------ | | emoji | string | required | The emoji character (e.g. "🔥") or Unicode hex (e.g. "1f525"). Strictly typed to available assets per provider. | | source | "fluent" \| "apple" \| "telegram" \| "noto" \| "twemoji" \| "blobmoji" | "fluent" | Visual emoji design provider. | | type | "3d" \| "anim" \| "flat" \| "modern" \| "mono" \| "pure" | Provider default | Visual style variant allowed for the chosen source. | | format | "webp" \| "png" \| "svg" \| "gif" \| "avif" \| "lottie" | Style default | Media container format strictly narrowed per provider & style. | | fallback | boolean \| EmojiSource \| { source, type } | false | Off: render nothing if missing. On: cascade to another pack, then native text. | | size | number | 40 | Render dimension in pixels (width and height). | | as | ElementType | "img" | Custom underlying container or component tag (e.g. Next.js Image). | | unoptimized | boolean | false | Disables image optimization when passed to custom containers. | | className | string | undefined | Custom CSS classes applied to element. | | style | CSSProperties | undefined | Inline styles applied to element. |

🗂 Library Subpaths

| Subpath | Description | | :------------------------ | :----------------------------------------------------------------------------------------------- | | @usespaceui/emoji | Headless Core: URL resolvers, manifest helpers, Unicode parsers, metadata, and TypeScript types. | | @usespaceui/emoji/react | React Components: <Emoji /> component, useEmoji hook, and React prop types. | | @usespaceui/emoji/data | Raw Datasets: emoji-manifest.json and emojiLib Unicode dictionary lookup tables. |

📦 Related Packages

🪪 License

MIT — Free for personal and commercial projects.

📚 Resources

🛠 Maintenance

If you discover a bug or have a feature request, please open an issue on GitHub.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme