react-emoji-styles 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 emoji-styles contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# react-emoji-styles
+
+React 18 and 19 primitives for consistent, accessible emoji across operating
+systems, providers, themes, SSR, and hydration.
+
+## Install
+
+```bash
+npm install react-emoji-styles
+```
+
+## Quick start
+
+```tsx
+import { Emoji, EmojiProvider, publicProviders } from "react-emoji-styles";
+import "react-emoji-styles/styles.css";
+
+export function App() {
+  return (
+    <EmojiProvider
+      provider={publicProviders.fluent3d}
+      fallbacks={[publicProviders.twemoji]}
+      nativeFallback={false}
+    >
+      <Emoji emoji="🚀" label="Launch project" size="xl" />
+    </EmojiProvider>
+  );
+}
+```
+
+The package also exports `EmojiToken`, `EmojiText`, `EmojiGrid`, provider
+configuration, semantic themes, and resolution hooks.
+
+- [Interactive demo](https://emoji-styles.space)
+- [React documentation](https://github.com/Blancochuy/emoji-styles/blob/master/docs/REACT.md)
+- [Source repository](https://github.com/Blancochuy/emoji-styles)
+
+## License
+
+Source code is MIT licensed. Provider artwork may use separate licenses; review
+the project's
+[third-party notices](https://github.com/Blancochuy/emoji-styles/blob/master/docs/THIRD_PARTY_NOTICES.md).

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactElement, ReactNode } from 'react';
+import * as emoji_styles from 'emoji-styles';
+import { EmojiStyle, EmojiProviderRef, EmojiSize, EmojiResolution, EmojiTheme, EmojiThemeProviderRef, EmojiAssetProvider, ResolvedEmojiToken, EmojiStylesConfig, getEmojiTokenDefinition } from 'emoji-styles';
+export { EmojiAssetProvider, EmojiData, EmojiProviderRef, EmojiSize, EmojiStyle, EmojiTheme, EmojiThemeProviderRef, EmojiTokenDefinition, ProviderLicense, ResolvedEmojiToken, SemanticTokenProvider, createCdnProvider, createMappedProvider, createSemanticTokenProvider, defineEmojiTheme, experimentalProviders, getAvailableEmojis, getEmojiData, hasEmoji, mergeEmojiThemes, providers, publicProviders, resolveEmojiToken, serializeEmojiTheme, tokenizeEmojiText, validateEmojiTheme } from 'emoji-styles';
+
+interface EmojiFallbackEvent {
+    emoji: string;
+    from: string | null;
+    to: string | null;
+    index: number;
+    native: boolean;
+}
+interface EmojiErrorEvent {
+    emoji: string;
+    url: string;
+    providerId: string;
+    index: number;
+}
+interface EmojiComponentProps {
+    emoji: string;
+    style?: EmojiStyle;
+    provider?: EmojiProviderRef;
+    fallbacks?: readonly EmojiProviderRef[];
+    /** Append native OS emoji after the configured provider chain. Defaults to true. */
+    nativeFallback?: boolean;
+    size?: EmojiSize;
+    className?: string;
+    /** Accessible label. Defaults to the CLDR label from the bundled dataset. */
+    label?: string;
+    /** @deprecated Use label. */
+    alt?: string;
+    decorative?: boolean;
+    loading?: "lazy" | "eager";
+    /** @deprecated Use loading="lazy" or loading="eager". */
+    lazy?: boolean;
+    /** @deprecated Use nativeFallback. */
+    fallback?: boolean;
+    onResolve?: (resolution: EmojiResolution) => void;
+    onFallback?: (event: EmojiFallbackEvent) => void;
+    onError?: (event: EmojiErrorEvent) => void;
+}
+declare function Emoji({ emoji, style: styleProp, provider: providerProp, fallbacks: fallbackProps, nativeFallback: nativeFallbackProp, size, className, label: labelProp, alt, decorative, loading: loadingProp, lazy, fallback, onResolve, onFallback, onError, }: EmojiComponentProps): react.JSX.Element;
+
+interface EmojiTextProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children" | "onError"> {
+    children: string;
+    provider?: EmojiProviderRef;
+    fallbacks?: readonly EmojiProviderRef[];
+    nativeFallback?: boolean;
+    size?: EmojiSize;
+    emojiClassName?: string;
+    lazy?: boolean;
+    loading?: "lazy" | "eager";
+    /** @deprecated Use nativeFallback. */
+    fallback?: boolean;
+    decorative?: boolean;
+    onResolve?: EmojiComponentProps["onResolve"];
+    onFallback?: EmojiComponentProps["onFallback"];
+    onError?: EmojiComponentProps["onError"];
+    getAlt?: (emoji: string) => string;
+    /** Replace selected tokens with design-system components while retaining the default renderer. */
+    renderEmoji?: (emoji: string, fallback: ReactElement, index: number) => ReactNode;
+}
+/** Render every supported emoji inside a text string through the provider system. */
+declare function EmojiText({ children, provider, fallbacks, nativeFallback, size, emojiClassName, lazy, loading, fallback, decorative, onResolve, onFallback, onError, getAlt, renderEmoji, ...spanProps }: EmojiTextProps): react.JSX.Element;
+
+interface EmojiTokenProps {
+    token: string;
+    theme?: EmojiTheme;
+    provider?: EmojiThemeProviderRef;
+    fallbacks?: readonly EmojiThemeProviderRef[];
+    nativeFallback?: boolean;
+    providers?: Readonly<Record<string, EmojiAssetProvider>>;
+    locale?: string;
+    label?: string;
+    decorative?: boolean;
+    size?: EmojiSize;
+    className?: string;
+    lazy?: boolean;
+    loading?: "lazy" | "eager";
+    /** @deprecated Use nativeFallback. */
+    fallback?: boolean;
+    onResolve?: (result: ResolvedEmojiToken) => void;
+    onFallback?: EmojiComponentProps["onFallback"];
+    onError?: EmojiComponentProps["onError"];
+}
+/** Render a design-system token through its theme without coupling UI copy to artwork. */
+declare function EmojiToken({ token, theme, provider, fallbacks, nativeFallback: nativeFallbackProp, providers, locale, label, decorative, size, className, lazy, loading, fallback, onResolve, onFallback, onError, }: EmojiTokenProps): react.JSX.Element;
+
+interface EmojiGridProps {
+    emojis: string[];
+    style?: EmojiStyle;
+    provider?: EmojiProviderRef;
+    fallbacks?: readonly EmojiProviderRef[];
+    nativeFallback?: boolean;
+    size?: EmojiSize;
+    className?: string;
+    gap?: number;
+    loading?: "lazy" | "eager";
+    decorative?: boolean;
+    getLabel?: (emoji: string, index: number) => string | undefined;
+    onResolve?: EmojiComponentProps["onResolve"];
+    onFallback?: EmojiComponentProps["onFallback"];
+    onError?: EmojiComponentProps["onError"];
+}
+/** A thin grid adapter that delegates all rendering and fallback behavior to Emoji. */
+declare function EmojiGrid({ emojis, style, provider, fallbacks, nativeFallback, size, className, gap, loading, decorative, getLabel, onResolve, onFallback, onError, }: EmojiGridProps): react.JSX.Element;
+
+interface EmojiContextValue {
+    defaultProvider: EmojiProviderRef;
+    fallbacks?: readonly EmojiProviderRef[];
+    nativeFallback?: boolean;
+    theme?: EmojiTheme;
+    locale?: string;
+    providers?: Readonly<Record<string, EmojiAssetProvider>>;
+}
+declare function useEmojiContext(): EmojiContextValue;
+interface EmojiProviderProps {
+    /** Project-level runtime policy, typically imported from emoji-styles.config.ts/json. */
+    config?: EmojiStylesConfig;
+    provider?: EmojiProviderRef;
+    fallbacks?: readonly EmojiProviderRef[];
+    /** Append native OS emoji after the configured provider chain. Defaults to true. */
+    nativeFallback?: boolean;
+    theme?: EmojiTheme;
+    locale?: string;
+    /** Registry used by serialized themes that reference custom providers by id. */
+    providers?: Readonly<Record<string, EmojiAssetProvider>>;
+    /** @deprecated Prefer provider for new integrations. */
+    defaultStyle?: EmojiStyle;
+    children: ReactNode;
+}
+declare function EmojiProvider({ config, provider, fallbacks, nativeFallback, theme, locale, providers, defaultStyle, children }: EmojiProviderProps): react.JSX.Element;
+
+interface UseEmojiResult {
+    url: string | null;
+    exists: boolean;
+    resolution: EmojiResolution | null;
+    loading: boolean;
+    error: Error | null;
+}
+declare function useEmoji(emoji: string, provider?: EmojiProviderRef, fallbacks?: readonly EmojiProviderRef[]): UseEmojiResult;
+
+interface UseEmojiTokenOptions {
+    theme?: EmojiTheme;
+    provider?: EmojiThemeProviderRef;
+    fallbacks?: readonly EmojiThemeProviderRef[];
+    nativeFallback?: boolean;
+    locale?: string;
+    providers?: Readonly<Record<string, EmojiAssetProvider>>;
+}
+interface UseEmojiTokenResult {
+    definition: ReturnType<typeof getEmojiTokenDefinition>;
+    result: ResolvedEmojiToken | null;
+    loading: boolean;
+    error: Error | null;
+}
+declare function useEmojiToken(token: string, options?: UseEmojiTokenOptions): UseEmojiTokenResult;
+
+declare function useEmojiTheme(): {
+    theme: emoji_styles.EmojiTheme | undefined;
+    locale: string | undefined;
+    providers: Readonly<Record<string, emoji_styles.EmojiAssetProvider>> | undefined;
+};
+
+export { Emoji, type EmojiComponentProps, type EmojiErrorEvent, type EmojiFallbackEvent, EmojiGrid, type EmojiGridProps, EmojiProvider, type EmojiProviderProps, EmojiText, type EmojiTextProps, EmojiToken, type EmojiTokenProps, type UseEmojiResult, type UseEmojiTokenOptions, type UseEmojiTokenResult, useEmoji, useEmojiContext, useEmojiTheme, useEmojiToken };

package/dist/index.js

@@ -0,0 +1,561 @@
+"use client";
+
+// src/Emoji.tsx
+import { useCallback, useEffect, useMemo as useMemo2, useRef, useState } from "react";
+import {
+  getEmojiMetadata,
+  getFallbackChain,
+  getEmojiUrl,
+  publicProviders as publicProviders2,
+  resolveEmoji,
+  SIZE_MAP
+} from "emoji-styles";
+
+// src/EmojiProvider.tsx
+import { createContext, useContext, useMemo } from "react";
+import {
+  publicProviders
+} from "emoji-styles";
+import { jsx } from "react/jsx-runtime";
+var EmojiContext = createContext({ defaultProvider: publicProviders.twemoji });
+function useEmojiContext() {
+  return useContext(EmojiContext);
+}
+function EmojiProvider({ config, provider, fallbacks, nativeFallback, theme, locale, providers: providers2, defaultStyle, children }) {
+  const configProvider = typeof config?.provider === "string" ? providers2?.[config.provider] ?? config.provider : config?.provider;
+  const configFallbacks = useMemo(() => config?.fallbacks?.map(
+    (fallback) => typeof fallback === "string" ? providers2?.[fallback] ?? fallback : fallback
+  ), [config?.fallbacks, providers2]);
+  const themeProvider = typeof theme?.defaultProvider === "string" ? providers2?.[theme.defaultProvider] ?? theme.defaultProvider : theme?.defaultProvider;
+  const themeFallbacks = useMemo(() => theme?.fallbacks?.map(
+    (fallback) => typeof fallback === "string" ? providers2?.[fallback] ?? fallback : fallback
+  ), [theme?.fallbacks, providers2]);
+  const value = useMemo(() => ({
+    defaultProvider: provider ?? defaultStyle ?? configProvider ?? themeProvider ?? publicProviders.twemoji,
+    fallbacks: fallbacks ?? configFallbacks ?? themeFallbacks,
+    nativeFallback: nativeFallback ?? config?.nativeFallback ?? theme?.nativeFallback,
+    theme,
+    locale,
+    providers: providers2
+  }), [provider, fallbacks, nativeFallback, config?.nativeFallback, configProvider, configFallbacks, themeFallbacks, theme, locale, providers2, defaultStyle, themeProvider]);
+  return /* @__PURE__ */ jsx(EmojiContext.Provider, { value, children });
+}
+
+// src/Emoji.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var DEFAULT_FALLBACKS = [publicProviders2.twemoji];
+function providerId(provider) {
+  return typeof provider === "string" ? provider : provider.id;
+}
+function sizeClass(size) {
+  if (typeof size !== "number") return `emoji-styles--size-${size}`;
+  const preset = Object.entries(SIZE_MAP).find(([, dimension]) => dimension === size)?.[0];
+  return preset ? `emoji-styles--size-${preset}` : "emoji-styles--size-custom";
+}
+function NativeEmojiGlyph({ emoji, dimension }) {
+  return /* @__PURE__ */ jsx2(
+    "svg",
+    {
+      className: "emoji-styles__native-glyph",
+      width: dimension,
+      height: dimension,
+      viewBox: "0 0 100 100",
+      "aria-hidden": "true",
+      focusable: "false",
+      children: /* @__PURE__ */ jsx2(
+        "text",
+        {
+          className: "emoji-styles__native-text",
+          x: "50",
+          y: "50",
+          textAnchor: "middle",
+          dominantBaseline: "central",
+          fontSize: "88",
+          children: emoji
+        }
+      )
+    }
+  );
+}
+function Emoji({
+  emoji,
+  style: styleProp,
+  provider: providerProp,
+  fallbacks: fallbackProps,
+  nativeFallback: nativeFallbackProp,
+  size = "md",
+  className = "",
+  label: labelProp,
+  alt,
+  decorative = false,
+  loading: loadingProp,
+  lazy,
+  fallback,
+  onResolve,
+  onFallback,
+  onError
+}) {
+  const context = useEmojiContext();
+  const provider = providerProp ?? styleProp ?? context.defaultProvider;
+  const fallbacks = fallbackProps ?? context.fallbacks ?? DEFAULT_FALLBACKS;
+  const nativeFallback = nativeFallbackProp ?? fallback ?? context.nativeFallback ?? true;
+  const hasNativeFallback = fallbacks.some((candidate) => providerId(candidate) === publicProviders2.native.id);
+  const resolutionFallbacks = useMemo2(
+    () => nativeFallback && !hasNativeFallback ? [...fallbacks, publicProviders2.native] : fallbacks,
+    [fallbacks, hasNativeFallback, nativeFallback]
+  );
+  const loading = loadingProp ?? (lazy === false ? "eager" : "lazy");
+  const onResolveRef = useRef(onResolve);
+  onResolveRef.current = onResolve;
+  const metadata = getEmojiMetadata(emoji);
+  const label = labelProp ?? alt ?? metadata?.label ?? emoji;
+  const dimension = typeof size === "number" ? size : SIZE_MAP[size] ?? SIZE_MAP.md;
+  const syncChain = useMemo2(
+    () => getFallbackChain(emoji, provider, resolutionFallbacks),
+    [emoji, provider, resolutionFallbacks]
+  );
+  const syncUrl = syncChain[0] ?? getEmojiUrl(emoji, provider);
+  const resolutionKey = `${emoji}:${providerId(provider)}:${resolutionFallbacks.map(providerId).join(",")}:${nativeFallback}`;
+  const [runtime, setRuntime] = useState(() => ({ key: resolutionKey, chain: syncChain, index: 0, exhausted: false }));
+  const current = runtime.key === resolutionKey ? runtime : { key: resolutionKey, chain: syncChain, index: 0, exhausted: false };
+  const currentUrl = current.chain[current.index] ?? syncUrl;
+  const isNativeProvider = providerId(provider) === publicProviders2.native.id;
+  const allowNative = isNativeProvider || hasNativeFallback || nativeFallback;
+  const showNative = isNativeProvider || allowNative && (!currentUrl || current.exhausted);
+  useEffect(() => {
+    let active = true;
+    setRuntime({ key: resolutionKey, chain: syncChain, index: 0, exhausted: false });
+    resolveEmoji(emoji, { provider, fallbacks: resolutionFallbacks }).then((resolution) => {
+      if (!active) return;
+      onResolveRef.current?.(resolution);
+      const selectedUrl = resolution.selected?.url;
+      if (selectedUrl && !syncChain.includes(selectedUrl)) {
+        setRuntime({
+          key: resolutionKey,
+          chain: [selectedUrl, ...syncChain],
+          index: 0,
+          exhausted: false
+        });
+      }
+    }).catch(() => {
+    });
+    return () => {
+      active = false;
+    };
+  }, [emoji, provider, resolutionKey]);
+  const handleError = useCallback(() => {
+    if (!currentUrl) return;
+    onError?.({
+      emoji,
+      url: currentUrl,
+      providerId: providerId(provider),
+      index: current.index
+    });
+    const nextIndex = current.index + 1;
+    const nextUrl = current.chain[nextIndex] ?? null;
+    if (nextUrl) {
+      setRuntime({ ...current, index: nextIndex });
+      onFallback?.({ emoji, from: currentUrl, to: nextUrl, index: nextIndex, native: false });
+      return;
+    }
+    setRuntime({ ...current, exhausted: true });
+    onFallback?.({ emoji, from: currentUrl, to: null, index: nextIndex, native: allowNative });
+  }, [allowNative, current, currentUrl, emoji, onError, onFallback, provider]);
+  const rootClassName = [
+    "emoji-styles",
+    sizeClass(size),
+    decorative ? "emoji-styles--decorative" : "",
+    className
+  ].filter(Boolean).join(" ");
+  if (showNative) {
+    return /* @__PURE__ */ jsx2(
+      "span",
+      {
+        className: `${rootClassName} emoji-styles--native`,
+        "data-emoji": emoji,
+        "data-provider": "native",
+        "data-size": dimension,
+        role: !decorative && metadata ? "img" : void 0,
+        "aria-label": !decorative && metadata ? label : void 0,
+        "aria-hidden": decorative || void 0,
+        children: /* @__PURE__ */ jsx2(NativeEmojiGlyph, { emoji, dimension })
+      }
+    );
+  }
+  if ((!currentUrl || current.exhausted) && !allowNative) {
+    return /* @__PURE__ */ jsx2(
+      "span",
+      {
+        className: `${rootClassName} emoji-styles--hidden`,
+        "data-emoji": emoji,
+        "data-provider": providerId(provider),
+        "data-size": dimension,
+        "aria-hidden": "true"
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx2(
+    "span",
+    {
+      className: rootClassName,
+      "data-emoji": emoji,
+      "data-provider": providerId(provider),
+      "data-size": dimension,
+      "aria-hidden": decorative || void 0,
+      children: /* @__PURE__ */ jsx2(
+        "img",
+        {
+          src: currentUrl,
+          alt: decorative ? "" : label,
+          width: dimension,
+          height: dimension,
+          loading,
+          decoding: "async",
+          className: "emoji-styles__image",
+          draggable: false,
+          onError: handleError
+        }
+      )
+    }
+  );
+}
+
+// src/EmojiText.tsx
+import {
+  getEmojiData,
+  tokenizeEmojiText
+} from "emoji-styles";
+import { jsx as jsx3 } from "react/jsx-runtime";
+function EmojiText({
+  children,
+  provider,
+  fallbacks,
+  nativeFallback,
+  size = "md",
+  emojiClassName,
+  lazy = true,
+  loading,
+  fallback,
+  decorative = false,
+  onResolve,
+  onFallback,
+  onError,
+  getAlt,
+  renderEmoji,
+  ...spanProps
+}) {
+  const tokens = tokenizeEmojiText(children);
+  return /* @__PURE__ */ jsx3("span", { ...spanProps, children: tokens.map((token, index) => {
+    if (token.type === "text") return token.value;
+    const defaultRenderer = /* @__PURE__ */ jsx3(
+      Emoji,
+      {
+        emoji: token.value,
+        provider,
+        fallbacks,
+        nativeFallback,
+        size,
+        className: emojiClassName,
+        alt: getAlt?.(token.value) ?? getEmojiData(token.value)?.alt ?? token.value,
+        lazy,
+        loading,
+        fallback,
+        decorative,
+        onResolve,
+        onFallback,
+        onError
+      }
+    );
+    return /* @__PURE__ */ jsx3("span", { "data-emoji-token": token.value, children: renderEmoji?.(token.value, defaultRenderer, index) ?? defaultRenderer }, `${token.value}-${index}`);
+  }) });
+}
+
+// src/EmojiToken.tsx
+import { useEffect as useEffect3, useMemo as useMemo4 } from "react";
+import {
+  createMappedProvider,
+  publicProviders as publicProviders3
+} from "emoji-styles";
+
+// src/useEmojiToken.ts
+import { useEffect as useEffect2, useMemo as useMemo3, useState as useState2 } from "react";
+import {
+  getEmojiTokenDefinition,
+  resolveEmojiToken
+} from "emoji-styles";
+function useEmojiToken(token, options = {}) {
+  const context = useEmojiContext();
+  const theme = options.theme ?? context.theme;
+  const locale = options.locale ?? context.locale;
+  const provider = options.provider;
+  const fallbacks = options.fallbacks;
+  const nativeFallback = options.nativeFallback ?? context.nativeFallback;
+  const providers2 = options.providers ?? context.providers;
+  const definition = useMemo3(
+    () => theme ? getEmojiTokenDefinition(theme, token) : null,
+    [theme, token]
+  );
+  const [state, setState] = useState2({
+    result: null,
+    loading: Boolean(theme && definition),
+    error: null
+  });
+  useEffect2(() => {
+    let active = true;
+    if (!theme || !definition) {
+      setState({
+        result: null,
+        loading: false,
+        error: new Error(!theme ? "EmojiToken requires an EmojiTheme" : `Unknown emoji token: ${token}`)
+      });
+      return () => {
+        active = false;
+      };
+    }
+    setState({ result: null, loading: true, error: null });
+    resolveEmojiToken(token, theme, { provider, fallbacks, nativeFallback, locale, providers: providers2 }).then((result) => {
+      if (active) setState({ result, loading: false, error: null });
+    }).catch((error) => {
+      if (active) setState({
+        result: null,
+        loading: false,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    });
+    return () => {
+      active = false;
+    };
+  }, [theme, definition, token, provider, fallbacks, nativeFallback, locale, providers2]);
+  return { definition, ...state };
+}
+
+// src/EmojiToken.tsx
+import { jsx as jsx4 } from "react/jsx-runtime";
+function providerForEmoji(provider, registry) {
+  if (!provider || typeof provider !== "string") return provider;
+  return registry?.[provider] ?? provider;
+}
+function EmojiToken({
+  token,
+  theme,
+  provider,
+  fallbacks,
+  nativeFallback: nativeFallbackProp,
+  providers: providers2,
+  locale,
+  label,
+  decorative,
+  size = "md",
+  className = "",
+  lazy = true,
+  loading,
+  fallback,
+  onResolve,
+  onFallback,
+  onError
+}) {
+  const context = useEmojiContext();
+  const effectiveTheme = theme ?? context.theme;
+  const nativeFallback = nativeFallbackProp ?? fallback ?? context.nativeFallback ?? effectiveTheme?.nativeFallback ?? true;
+  const registry = providers2 ?? context.providers;
+  const { definition, result, error } = useEmojiToken(token, {
+    theme: effectiveTheme,
+    provider,
+    fallbacks,
+    nativeFallback,
+    providers: registry,
+    locale
+  });
+  const resolvedLabel = label ?? result?.label ?? definition?.label ?? token;
+  const isDecorative = decorative ?? result?.decorative ?? definition?.decorative ?? false;
+  const emoji = result?.emoji ?? definition?.emoji;
+  const fallbackProvider = providerForEmoji(
+    provider ?? definition?.provider ?? effectiveTheme?.defaultProvider ?? context.defaultProvider,
+    registry
+  );
+  const assetProvider = useMemo4(() => {
+    if (!result?.asset || !emoji) return null;
+    return createMappedProvider({
+      id: `token-${token.replace(/\./g, "-")}`,
+      label: resolvedLabel,
+      version: result.themeVersion,
+      assets: { [emoji]: result.asset.url },
+      format: result.asset.format,
+      local: result.asset.local,
+      license: result.asset.license,
+      fallback: typeof fallbackProvider === "object" ? fallbackProvider : void 0
+    });
+  }, [result, emoji, token, resolvedLabel, fallbackProvider]);
+  const emojiFallbacks = useMemo4(
+    () => (fallbacks ?? effectiveTheme?.fallbacks ?? []).map((candidate) => providerForEmoji(candidate, registry)).filter((candidate) => Boolean(candidate)),
+    [fallbacks, effectiveTheme?.fallbacks, registry]
+  );
+  useEffect3(() => {
+    if (result) onResolve?.(result);
+  }, [result, onResolve]);
+  if (!emoji) {
+    return /* @__PURE__ */ jsx4("span", { className, "data-emoji-token": token, "data-emoji-error": error?.message, children: token });
+  }
+  const renderProvider = result?.source === "native" ? publicProviders3.native : assetProvider ?? fallbackProvider ?? publicProviders3.native;
+  return /* @__PURE__ */ jsx4(
+    "span",
+    {
+      className,
+      "data-emoji-token": token,
+      "data-emoji-theme": effectiveTheme?.id,
+      "data-emoji-source": result?.source ?? "pending",
+      "aria-hidden": isDecorative || void 0,
+      children: /* @__PURE__ */ jsx4(
+        Emoji,
+        {
+          emoji,
+          provider: renderProvider,
+          fallbacks: emojiFallbacks,
+          nativeFallback,
+          size,
+          alt: isDecorative ? "" : resolvedLabel,
+          lazy,
+          loading,
+          decorative: isDecorative,
+          onFallback,
+          onError
+        }
+      )
+    }
+  );
+}
+
+// src/EmojiGrid.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+function EmojiGrid({
+  emojis,
+  style,
+  provider,
+  fallbacks,
+  nativeFallback,
+  size = "md",
+  className = "",
+  gap = 4,
+  loading = "lazy",
+  decorative = false,
+  getLabel,
+  onResolve,
+  onFallback,
+  onError
+}) {
+  return /* @__PURE__ */ jsx5(
+    "div",
+    {
+      className: ["emoji-styles-grid", className].filter(Boolean).join(" "),
+      "data-gap": gap,
+      role: "list",
+      children: emojis.map((emoji, index) => /* @__PURE__ */ jsx5("span", { className: "emoji-styles-grid__cell", role: "listitem", children: /* @__PURE__ */ jsx5(
+        Emoji,
+        {
+          emoji,
+          style,
+          provider,
+          fallbacks,
+          nativeFallback,
+          size,
+          label: getLabel?.(emoji, index),
+          decorative,
+          loading,
+          onResolve,
+          onFallback,
+          onError
+        }
+      ) }, `${emoji}-${index}`))
+    }
+  );
+}
+
+// src/useEmoji.ts
+import { useEffect as useEffect4, useMemo as useMemo5, useState as useState3 } from "react";
+import {
+  getEmojiUrl as getEmojiUrl2,
+  hasEmoji,
+  publicProviders as publicProviders4,
+  resolveEmoji as resolveEmoji2
+} from "emoji-styles";
+var DEFAULT_HOOK_FALLBACKS = [publicProviders4.native];
+function useEmoji(emoji, provider = publicProviders4.twemoji, fallbacks = DEFAULT_HOOK_FALLBACKS) {
+  const fallbackKey = fallbacks.map(
+    (fallback) => typeof fallback === "string" ? fallback : fallback.id
+  ).join(",");
+  const initial = useMemo5(
+    () => ({ url: getEmojiUrl2(emoji, provider), exists: hasEmoji(emoji) }),
+    [emoji, provider]
+  );
+  const [state, setState] = useState3({
+    resolution: null,
+    loading: initial.exists,
+    error: null
+  });
+  useEffect4(() => {
+    let active = true;
+    if (!initial.exists) {
+      setState({ resolution: null, loading: false, error: null });
+      return () => {
+        active = false;
+      };
+    }
+    setState({ resolution: null, loading: true, error: null });
+    resolveEmoji2(emoji, { provider, fallbacks }).then((resolution) => {
+      if (active) setState({ resolution, loading: false, error: null });
+    }).catch((error) => {
+      if (active) setState({
+        resolution: null,
+        loading: false,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    });
+    return () => {
+      active = false;
+    };
+  }, [emoji, provider, fallbackKey, initial.exists]);
+  return {
+    url: state.resolution?.selected?.url ?? initial.url,
+    exists: initial.exists,
+    ...state
+  };
+}
+
+// src/useEmojiTheme.ts
+function useEmojiTheme() {
+  const context = useEmojiContext();
+  return {
+    theme: context.theme,
+    locale: context.locale,
+    providers: context.providers
+  };
+}
+
+// src/index.ts
+import { providers, publicProviders as publicProviders5, experimentalProviders, createCdnProvider, createMappedProvider as createMappedProvider2, tokenizeEmojiText as tokenizeEmojiText2, getAvailableEmojis, getEmojiData as getEmojiData2, hasEmoji as hasEmoji2, defineEmojiTheme, resolveEmojiToken as resolveEmojiToken2, validateEmojiTheme, mergeEmojiThemes, serializeEmojiTheme, createSemanticTokenProvider } from "emoji-styles";
+export {
+  Emoji,
+  EmojiGrid,
+  EmojiProvider,
+  EmojiText,
+  EmojiToken,
+  createCdnProvider,
+  createMappedProvider2 as createMappedProvider,
+  createSemanticTokenProvider,
+  defineEmojiTheme,
+  experimentalProviders,
+  getAvailableEmojis,
+  getEmojiData2 as getEmojiData,
+  hasEmoji2 as hasEmoji,
+  mergeEmojiThemes,
+  providers,
+  publicProviders5 as publicProviders,
+  resolveEmojiToken2 as resolveEmojiToken,
+  serializeEmojiTheme,
+  tokenizeEmojiText2 as tokenizeEmojiText,
+  useEmoji,
+  useEmojiContext,
+  useEmojiTheme,
+  useEmojiToken,
+  validateEmojiTheme
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "react-emoji-styles",
+  "version": "0.1.0",
+  "description": "React primitives for consistent emoji, semantic asset mappings, and automatic text rendering",
+  "sideEffects": [
+    "./styles.css"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": [
+    "dist",
+    "styles.css"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "emoji-styles": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 <20.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "6.6.3",
+    "@testing-library/react": "16.3.0",
+    "@types/react": "^18.3.0",
+    "jsdom": "25.0.1",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blancochuy/emoji-styles.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/Blancochuy/emoji-styles/issues"
+  },
+  "homepage": "https://emoji-styles.space",
+  "keywords": [
+    "react",
+    "emoji",
+    "component",
+    "icons",
+    "design-system",
+    "semantic-ui"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external react --external emoji-styles",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsup src/index.ts --format esm --dts --watch --external react"
+  }
+}

package/styles.css

@@ -0,0 +1,73 @@
+.emoji-styles {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 auto;
+  vertical-align: -0.125em;
+  line-height: 1;
+}
+
+.emoji-styles__image {
+  position: relative;
+  display: block;
+  max-width: 100%;
+  max-height: 100%;
+  object-fit: contain;
+}
+
+.emoji-styles__image[src*="/SerenityOS/serenity@"][src*="/Base/res/emoji/"] {
+  image-rendering: pixelated;
+}
+
+.emoji-styles--hidden {
+  display: none;
+}
+
+.emoji-styles--native {
+  font-family: "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif;
+}
+
+.emoji-styles__native-glyph {
+  display: block;
+  flex: 0 0 auto;
+  overflow: visible;
+}
+
+.emoji-styles__native-text {
+  font-family: "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif;
+}
+
+.emoji-styles--size-xs { width: 12px; height: 12px; font-size: 12px; }
+.emoji-styles--size-sm { width: 16px; height: 16px; font-size: 16px; }
+.emoji-styles--size-md { width: 20px; height: 20px; font-size: 20px; }
+.emoji-styles--size-lg { width: 24px; height: 24px; font-size: 24px; }
+.emoji-styles--size-xl { width: 32px; height: 32px; font-size: 32px; }
+.emoji-styles--size-2xl { width: 40px; height: 40px; font-size: 40px; }
+.emoji-styles--size-3xl { width: 48px; height: 48px; font-size: 48px; }
+
+.emoji-styles-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(2rem, 1fr));
+  gap: 0.25rem;
+}
+
+.emoji-styles-grid__cell {
+  display: grid;
+  place-items: center;
+}
+
+.emoji-styles-grid[data-gap="0"] { gap: 0; }
+.emoji-styles-grid[data-gap="2"] { gap: 0.125rem; }
+.emoji-styles-grid[data-gap="4"] { gap: 0.25rem; }
+.emoji-styles-grid[data-gap="6"] { gap: 0.375rem; }
+.emoji-styles-grid[data-gap="8"] { gap: 0.5rem; }
+.emoji-styles-grid[data-gap="12"] { gap: 0.75rem; }
+.emoji-styles-grid[data-gap="16"] { gap: 1rem; }
+
+@media (prefers-reduced-motion: reduce) {
+  .emoji-styles__image {
+    animation: none;
+    transition: none;
+  }
+}