Emoji icon API

Find each public package entry and the current core, React, provider, and accent contracts.

Export map

Package entry	Public family
`@ghost-ui/core/emoji-icon-picker`	Data-free core types and functions, including accent string normalization.
`@ghost-ui/core/emoji-icon-picker-react`	`useEmojiIconPicker`, `useEmojiIconCatalog`, state option/category/state types.
`@ghost-ui/core/emoji-icon-picker-data`	`emojiIconPickerData`, `emojiIconPickerCategories`, `emojiIconPickerCatalog`.
`@ghost-ui/core/emoji-icon-picker-adapters`	`EmojiIconAdapterResult`, `fromEmojibase`, `fromEmojiMart`, `fromFrimousse`.
`@ghost-ui/core/emoji-icon-picker-provider`	Provider definition/options/result types and `createEmojiIconProvider`.
`@ghost-ui/core/emoji-icon-picker-lucide`	`LucideEmojiIconDefinition`, `createLucideEmojiIconProvider`.
`@ghost-ui/core/emoji-icon-picker-accent`	Accent source/options types, `accentFromPixels`, `detectEmojiIconAccent`.
`@ghost-ui/core/components/emoji-icon-picker`	Styled `EmojiIconPicker` owner/parts and its context hook; see component API.

Core functions

Export	Signature	Meaning and boundary
`createEmojiIconCatalog`	`<M>(items: readonly EmojiIconItem<M>[], categoryOrder?: readonly string[]) => EmojiIconCatalog<M>`	Copies/freezes catalog arrays/content; throws on invalid or duplicate item/variant identity or content.
`normalizeEmojiIconSearch`	`(value: string) => string`	Folds case, diacritics, punctuation separators, colons, and underscores for matching.
`searchEmojiIconCatalog`	`<M>(catalog, query, options?: EmojiIconSearchOptions<M>) => readonly EmojiIconItem<M>[]`	Ranked search; options are category, filter, limit, score. Limit floors and clamps at zero.
`resolveEmojiIcon`	`<M>(catalog, selection: EmojiIconSelection, tone?: EmojiIconTone) => ResolvedEmojiIcon<M> \| null`	Resolves base or exact variant; returns null for missing/disabled item or invalid explicit variant.
`groupEmojiIcons`	`<M>(items, categoryOrder?: readonly string[]) => readonly EmojiIconGroup<M>[]`	Groups on primary category in stable item order.
`recordEmojiIconUsage`	`(records, id, now?: number) => readonly EmojiIconUsageRecord[]`	Returns updated immutable list; empty ID leaves a copied list; no persistence.
`getFrequentEmojiIcons`	`<M>(catalog, records, limit?: number) => readonly EmojiIconItem<M>[]`	Sorts count, recency, catalog order; default limit 32.
`normalizeEmojiIconAccent`	`(value: unknown) => string \| null`	Returns normalized CSS hex or null.

React hooks

useEmojiIconPicker<M>(options: EmojiIconPickerOptions<M>) returns catalog, controlled/current values, visible and selected items, state setters, and Combobox props. value, query, category, tone, and open are independently controllable with matching on…Change callbacks; defaultValue, defaultQuery, defaultCategory, defaultTone, and defaultOpen initialize uncontrolled values. Defaults: empty items/categories, null value/category, empty query, tone 0, closed, inline=false, closeOnSelect=true, disabled=false, virtualized=false, status="ready". columns is optional. filter and score constrain/rank items. Selection callbacks receive (value: EmojiIconSelection | null, item: ResolvedEmojiIcon | null).

useEmojiIconCatalog(resolver, key?) accepts (signal: AbortSignal) => EmojiIconCatalog | Promise<EmojiIconCatalog> and returns { status, catalog?, error?, reload }. It cancels stale/unmounted work; errors are exposed without automatic retry. useEmojiIconPickerContext() is exported from @ghost-ui/core/components/emoji-icon-picker; it returns the state for a styled Root and throws outside that context.

Adapters, providers, and accent

fromEmojibase(data, shortcodes?, categoryLabels?), fromEmojiMart(data, custom = []), and fromFrimousse(data) return EmojiIconAdapterResult (items, categories, optional categoryLabels). They consume caller-supplied data and do not import vendor packages.

createEmojiIconProvider<P>(options: { id, definitions, capabilities? }) returns id, items, categories, optional capabilities, and renderIcon(content, props): ReactNode. It throws for empty provider/name/label, duplicate names, missing renderers, or non-array definitions; unknown provider/name or unsupported style/weight/corners returns null. createLucideEmojiIconProvider(definitions) accepts static Lucide definitions and supports outline, round corners, and stroke width; it does not accept arbitrary icon geometry.

accentFromPixels(pixels: Uint8ClampedArray): string | null returns a sampled color or null for unusable pixels. detectEmojiIconAccent(source, options?): Promise<string | null> samples { emoji } or { src }; options include signal and size (default 64, clamped to 16–128). Unsupported canvas, tainted image, load failure, or abort returns null.

Core types

Core types are EmojiIconTone, EmojiIconContent, EmojiIconProvider<M>, EmojiIconVariant, EmojiIconItem<M>, EmojiIconSelection, ResolvedEmojiIcon<M>, EmojiIconSearchOptions<M>, EmojiIconGroup<M>, EmojiIconUsageRecord, and EmojiIconCatalog<M>. Exact required fields, identity semantics, and content discriminants are in Emoji icon data; state ownership and cancellation are in Emoji icon state.