Emoji icon data

Item identity and content

An EmojiIconItem requires a stable, non-empty id, non-empty label, and content. Content is discriminated: { type: "emoji", text, hexcode? }, { type: "image", src, alt? }, or { type: "icon", name, provider?, style?, weight?, corners?, strokeWidth? }. Optional fields include category, additional categories, keywords, shortcodes, CSS hex accent, variants, generic metadata, and disabled.

The item id identifies the record across renderers and sessions. A variant's id is a separate exact source identity, for example a specific tone. Store { id, variantId } when the exact variant must survive unmounting. A numeric tone is only a resolution preference; it is not a substitute for an exact variantId when source variants are irregular. The library does not synthesize missing variants.

123456789import type { EmojiIconItem, EmojiIconSelection } from "@ghost-ui/core/emoji-icon-picker";

const item: EmojiIconItem<{ assetKey: string }> = {
  id: "brand:wave", label: "Wave",
  content: { type: "emoji", text: "👋", hexcode: "1F44B" },
  variants: [{ id: "tone-3-source", tone: 3, content: { type: "emoji", text: "👋🏽", hexcode: "1F44B-1F3FD" } }],
  metadata: { assetKey: "wave-v1" },
};
const saved: EmojiIconSelection = { id: item.id, variantId: "tone-3-source" };

Catalog creation throws on a missing/empty ID or label, duplicate item ID, invalid/empty content payload, or duplicate/empty variant ID. It freezes its copied arrays and content; nested custom metadata is not deep-copied or frozen. Validate untrusted records before passing them in.

Category, order, and filtering

category is the primary display group. categories adds filter membership without changing that primary group. categoryOrder seeds catalog grouping order; categories found on items are appended. Category IDs are stable data keys, while labels and localization belong to the caller. groupEmojiIcons groups by primary category only.

Search folds case, diacritics, colons, underscores, and separators. It ranks exact matches, prefixes, then all-token matches, preserving original order within equal rank and score. It searches IDs, labels, keywords, shortcodes, Unicode values, and icon metadata. lookup also recognizes an exact ID, native emoji, shortcode, or hexcode. Search filter applies caller policy; a score callback only changes order within a match class. Disabled items can appear in data/search results but resolveEmojiIcon returns null for them.

Data sources and providers

The optional emoji-icon-picker-data export provides emojiIconPickerData, emojiIconPickerCategories, and emojiIconPickerCatalog from Unicode 17 data. The core entry does not import this dataset. fromEmojibase(data, shortcodes?, categoryLabels?), fromEmojiMart(data, custom?), and fromFrimousse(data) convert caller-supplied structures and return { items, categories, categoryLabels? }. They do not import those vendors. Keep source version, allowed records, locale, and category policy with the application.

createEmojiIconProvider({ id, definitions, capabilities? }) creates namespaced icon records and a renderIcon(content, props) resolver. createLucideEmojiIconProvider(definitions) builds the static Lucide variant. A provider advertises supported styles, weights, corners, and stroke features; unsupported or unknown provider/name/style/weight/corner resolutions return null. The contract does not transform one icon family into another. Import only the icon definitions the application uses.

Connect an icon provider

Install lucide-react in the application and choose explicit definitions. This example shares the catalog/selection contract with Unicode items; the provider only supplies records and a renderer. The wrapper callback keeps the picker’s resolved-item argument separate from the provider’s icon-render props.

123456789101112import { Brain, Bot } from "lucide-react";
import { createLucideEmojiIconProvider } from "@ghost-ui/core/emoji-icon-picker-lucide";
import { EmojiIconPicker } from "@ghost-ui/core/components/emoji-icon-picker";
const provider = createLucideEmojiIconProvider([
  { name: "brain", label: "Research", icon: Brain, tags: ["think"] },
  { name: "bot", label: "Assistant", icon: Bot, tags: ["agent"] },
]);
export function RolePicker() {
  return <EmojiIconPicker items={provider.items}
    renderIcon={content => provider.renderIcon(content)}
    triggerProps={{ "aria-label": "Choose a role icon" }} />;
}

Accent values

accent is an optional CSS hex hint (#RGB, #RRGGBB, or #RRGGBBAA); it is not inferred from Unicode hexcode. normalizeEmojiIconAccent returns the trimmed lowercase value or null. Explicit canvas sampling is in the optional accent entry; unsupported canvas, tainted cross-origin images, load errors, and abort resolve to null. The caller decides whether to sample or what fallback to show.

See Emoji icon state for selection and usage updates, and API reference for exported shapes and functions.

Localization and data size

The bundled dataset is Emojibase17.0.0 English Unicode data. It supplies labels/search terms, not a translation service or an image font. For another locale, load the matching source data in your application and pass it through fromEmojibase, including shortcodes and category labels where needed. Keep stable IDs across locale changes; translate labels and keywords rather than saved selections. Search normalization is not translation or linguistic stemming.

No network loader runs on import of the data-free core. Import the optional data entry deliberately, or dynamically import your locale data when opening the picker. Structural adapters accept supplied records; they do not install vendor packages or guarantee that differently versioned datasets contain the same variants. Persist source identity/version when your application must later resolve an exact choice.

Icon providers contain React renderers and selected definitions; do not serialize their component functions. Persist EmojiIconSelection, then resolve it against the current catalog/provider. Image assets and cross-origin policy remain application-owned; a valid catalog record is not approval to load an untrusted URL.