emoji-picker-react 4.22.3 → 5.0.1

package/dist/hooks/useRegisterRegion.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { NavigationRegionKind } from '../state/navigationRegistry';
+/**
+ * Register a semantic focus region root with the Root-scoped navigation
+ * registry.
+ *
+ * - Registers after mount and unregisters on unmount; omitted regions
+ *   (null element) stay absent from the graph — there are no placeholder
+ *   or dead graph nodes.
+ * - `presenceDeps` reruns registration when presence-affecting state
+ *   changes (e.g. a tab bar that unmounts below two categories).
+ * - Portal roots (outside the Root DOM element) are unsupported: dev
+ *   warns and the region is excluded from traversal.
+ * - A second singleton registration throws in development and is ignored
+ *   (first wins) in production.
+ */
+export declare function useRegisterRegion(kind: NavigationRegionKind, ref: React.RefObject<Element | null> & {
+    subscribe?: (listener: () => void) => () => void;
+}, presenceDeps?: readonly unknown[]): void;
+/**
+ * Claim a structural singleton slot (Viewport/Preview)
+ * without registering a focus region. Same duplicate policy as regions.
+ */
+export declare function useSingletonClaim(kind: string): void;

package/dist/hooks/useResolvedEmojiData.d.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import type { EmojiData } from '../types/exposedTypes';
+/**
+ * Asynchronous dataset source, e.g.
+ * `() => import('emoji-picker-react/data/emojis-fr')`.
+ * Hoist it (module scope or useCallback): a new function identity loads
+ * again.
+ */
+export type EmojiDataLoaderOptions = {
+    signal?: AbortSignal;
+};
+export type EmojiDataLoader = (options: EmojiDataLoaderOptions) => Promise<EmojiData | {
+    default: EmojiData;
+}>;
+export type EmojiDataInput = EmojiData | EmojiDataLoader;
+export type EmojiDataState = {
+    loading: boolean;
+    error: Error | null;
+    retry: () => void;
+};
+type Resolved = EmojiDataState & {
+    data: EmojiData | undefined;
+};
+/**
+ * Resolve Root's `emojiData` input to a synchronous dataset:
+ * - an object is used as-is (synchronous, SSR-safe);
+ * - a loader is awaited (Root renders empty, `Loading` shows meanwhile);
+ * - absent: the registered default dataset when an entry registered it
+ *   (the default picker always does), otherwise the bundled English
+ *   dataset is loaded on demand (a separate chunk in ESM builds).
+ * `data: undefined` means "the registered default".
+ */
+export declare function useResolvedEmojiData(input?: EmojiDataInput, enabled?: boolean): Resolved;
+export declare const DataLoadingProvider: React.Provider<EmojiDataState>;
+export declare function useIsEmojiDataLoading(): boolean;
+export declare function useEmojiDataState(): EmojiDataState;
+export {};

package/dist/hooks/useScrollCategoryIntoView.d.ts

@@ -1 +1 @@
-export declare function useScrollCategoryIntoView(): (category: string) => void;
+export declare function useScrollCategoryIntoView(): (category: string) => void;

package/dist/hooks/useSearchController.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+export declare function useIsControlledSearch(): boolean;
+/** Accepted raw value: the controlled prop, or the committed value. */
+export declare function useAcceptedSearchValue(): string;
+export declare function useSearchInputController(): {
+    value: string;
+    handleChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    handleCompositionStart: () => void;
+    handleCompositionEnd: (event: React.CompositionEvent<HTMLInputElement>) => void;
+    isControlled: boolean;
+};
+/** Grid type-to-search transition. */
+export declare function useTypeToSearchKey(): (key: string) => void;
+/** Explicit programmatic proposals; no input or input-controller effects required. */
+export declare function useSetSearchValue(): (value: string) => void;
+/** Clear-button / Escape transition: proposes/commits ''. */
+export declare function useClearSearchValue(): () => void;

package/dist/hooks/useSearchResults.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Number of distinct emojis the list actually shows for the active search,
+ * or null while no search is applied (or its results are not computed
+ * yet). Uses the same predicates as the list itself, so configured
+ * categories, emojiVersion, hiddenEmojis, platform support and failed
+ * images are all accounted for — the raw match dictionary is not.
+ */
+export declare function useVisibleSearchResultCount(): number | null;

package/dist/hooks/useSetVariationPicker.d.ts

@@ -1,2 +1,2 @@
-import { NullableElement } from '../DomUtils/selectors';
-export default function useSetVariationPicker(): (element: NullableElement) => void;
+import { NullableElement } from '../DomUtils/selectors';
+export default function useSetVariationPicker(): (element: NullableElement) => void;

package/dist/hooks/useShouldHideCustomEmojis.d.ts

@@ -1 +1 @@
-export declare function useShouldHideCustomEmojis(): boolean;
+export declare function useShouldHideCustomEmojis(): boolean;

package/dist/hooks/useShouldShowSkinTonePicker.d.ts

@@ -1,4 +1,4 @@
-import { SkinTonePickerLocation } from '../types/exposedTypes';
-export declare function useShouldShowSkinTonePicker(): (location: SkinTonePickerLocation) => boolean;
-export declare function useIsSkinToneInSearch(): boolean;
-export declare function useIsSkinToneInPreview(): boolean;
+import { SkinTonePickerLocation } from '../types/exposedTypes';
+export declare function useShouldShowSkinTonePicker(): (location: SkinTonePickerLocation) => boolean;
+export declare function useIsSkinToneInSearch(): boolean;
+export declare function useIsSkinToneInPreview(): boolean;

package/dist/index.d.mts

@@ -0,0 +1,376 @@
+import * as React from 'react';
+
+type EmojiClickData = {
+    activeSkinTone: SkinTones;
+    unified: string;
+    unifiedWithoutSkinTone: string;
+    emoji: string;
+    names: string[];
+    imageUrl: string;
+    getImageUrl: (emojiStyle?: EmojiStyleValue) => string;
+    isCustom: boolean;
+};
+type CategoryConfig = {
+    category: Categories;
+    name: string;
+    icon?: React.ReactNode;
+    /**
+     * Selects a `CustomEmoji` group for `Categories.CUSTOM` entries. Each
+     * grouped entry renders its own section and nav tab; ungrouped entries
+     * share the classic customs bucket.
+     */
+    group?: string;
+};
+type CategoryIcons = Partial<Record<Categories, React.ReactNode>>;
+type EmojiData = {
+    categories: Partial<Record<Categories, CategoryConfig>>;
+    emojis: Record<string, DataEmoji$1[]>;
+};
+interface DataEmoji$1 {
+    n: string[];
+    u: string;
+    v?: string[];
+    a: string;
+}
+declare enum SuggestionMode {
+    RECENT = "recent",
+    FREQUENT = "frequent"
+}
+type SuggestionModeValue = SuggestionMode | 'recent' | 'frequent';
+declare enum EmojiStyle {
+    NATIVE = "native",
+    APPLE = "apple",
+    TWITTER = "twitter",
+    GOOGLE = "google",
+    FACEBOOK = "facebook"
+}
+type EmojiStyleValue = EmojiStyle | 'native' | 'apple' | 'twitter' | 'google' | 'facebook';
+declare enum Theme {
+    DARK = "dark",
+    LIGHT = "light",
+    AUTO = "auto"
+}
+type ThemeValue = Theme | 'dark' | 'light' | 'auto';
+declare enum SkinTones {
+    NEUTRAL = "neutral",
+    LIGHT = "1f3fb",
+    MEDIUM_LIGHT = "1f3fc",
+    MEDIUM = "1f3fd",
+    MEDIUM_DARK = "1f3fe",
+    DARK = "1f3ff"
+}
+/** A skin tone as the enum or its literal value (`'neutral'`, `'1f3fb'`, …). */
+type SkinTonesValue = SkinTones | 'neutral' | '1f3fb' | '1f3fc' | '1f3fd' | '1f3fe' | '1f3ff';
+declare enum Categories {
+    SUGGESTED = "suggested",
+    CUSTOM = "custom",
+    SMILEYS_PEOPLE = "smileys_people",
+    ANIMALS_NATURE = "animals_nature",
+    FOOD_DRINK = "food_drink",
+    TRAVEL_PLACES = "travel_places",
+    ACTIVITIES = "activities",
+    OBJECTS = "objects",
+    SYMBOLS = "symbols",
+    FLAGS = "flags"
+}
+declare enum SkinTonePickerLocation {
+    SEARCH = "SEARCH",
+    PREVIEW = "PREVIEW",
+    /**
+     * No built-in placement: render the `SkinTone` primitive wherever you
+     * want it, or drive the tone through `skinTone` / `useSkinTone()`.
+     */
+    NONE = "NONE"
+}
+
+declare enum EmojiProperties {
+    name = "n",
+    unified = "u",
+    variations = "v",
+    added_in = "a",
+    imgUrl = "imgUrl"
+}
+interface DataEmoji extends WithName {
+    /** Exact rendered identity; canonical unified remains the search identity. */
+    renderUnified?: string;
+    /** Stored recent identity when the active tone has no matching variation. */
+    fallbackUnified?: string;
+    [EmojiProperties.unified]: string;
+    [EmojiProperties.variations]?: string[];
+    [EmojiProperties.added_in]: string;
+    [EmojiProperties.imgUrl]?: string;
+}
+type WithName = {
+    [EmojiProperties.name]: string[];
+};
+
+type CustomEmoji = {
+    names: string[];
+    [EmojiProperties.imgUrl]: string;
+    id: string;
+    /**
+     * Optional group name. Customs sharing a group render as their own
+     * category section; ungrouped customs keep the single shared bucket.
+     * Reference the group from a `{ category: Categories.CUSTOM, group }`
+     * entry in the `categories` prop to place and name the section.
+     * https://github.com/ealush/emoji-picker-react/issues/510
+     */
+    group?: string;
+};
+
+type GetEmojiUrl = (unified: string, style: EmojiStyleValue) => string;
+
+/**
+ * Asynchronous dataset source, e.g.
+ * `() => import('emoji-picker-react/data/emojis-fr')`.
+ * Hoist it (module scope or useCallback): a new function identity loads
+ * again.
+ */
+type EmojiDataLoaderOptions = {
+    signal?: AbortSignal;
+};
+type EmojiDataLoader = (options: EmojiDataLoaderOptions) => Promise<EmojiData | {
+    default: EmojiData;
+}>;
+type EmojiDataInput = EmojiData | EmojiDataLoader;
+
+type CategoriesConfig = CategoryConfig[];
+type UserCategoryConfig = Array<Categories | CategoryConfig>;
+
+/**
+ * Every user-facing string the picker renders or announces. All keys are
+ * optional on the `labels` prop; anything omitted keeps its English
+ * default. Category names come from `categories` / localized `emojiData`,
+ * and the preview caption from `previewConfig.defaultCaption`.
+ */
+type PickerLabels = {
+    searchPlaceholder: string;
+    /** Accessible name of the search input. */
+    searchLabel: string;
+    searchClear: string;
+    /** Live-region announcement and visible empty state. */
+    searchResultsNone: string;
+    searchResultsOne: string;
+    /** `%n` is replaced with the result count. */
+    searchResultsMany: string;
+    categoryNavigation: string;
+    reactions: string;
+    expandReactions: string;
+    /** Shown by the Loading part while the dataset loads. */
+    loading: string;
+    loadingError: string;
+    retryLoading: string;
+    skinToneNeutral: string;
+    skinToneLight: string;
+    skinToneMediumLight: string;
+    skinToneMedium: string;
+    skinToneMediumDark: string;
+    skinToneDark: string;
+};
+type PickerConfigInternal = {
+    emojiVersion: string | null;
+    searchPlaceHolder: string;
+    searchPlaceholder: string;
+    searchClearButtonLabel: string;
+    defaultSkinTone: SkinTonesValue;
+    skinTonesDisabled: boolean;
+    autoFocusSearch: boolean;
+    emojiStyle: EmojiStyleValue;
+    categories: CategoriesConfig;
+    theme: ThemeValue;
+    suggestedEmojisMode: SuggestionModeValue;
+    lazyLoadEmojis: boolean;
+    previewConfig: PreviewConfig;
+    className: string;
+    height: PickerDimensions;
+    width: PickerDimensions;
+    style: React.CSSProperties;
+    getEmojiUrl: GetEmojiUrl;
+    searchDisabled: boolean;
+    skinTonePickerLocation: SkinTonePickerLocation;
+    unicodeToHide: Set<string>;
+    customEmojis: CustomEmoji[];
+    reactionsDefaultOpen: boolean;
+    reactions: string[];
+    open: boolean;
+    allowExpandReactions: boolean;
+    hiddenEmojis: string[];
+    emojiData?: EmojiData;
+    categoryIcons: CategoryIcons;
+    nonce?: string;
+    /**
+     * Controlled search value (raw user text). When present, it is the
+     * accepted visible source of truth; user edits emit `onSearchChange`
+     * proposals instead of committing locally.
+     */
+    searchValue?: string;
+    /** Uncontrolled initial search value, read once per mounted lifetime. */
+    defaultSearchValue?: string;
+    /** Emitted synchronously with each committed (uncontrolled) or proposed (controlled) user edit. */
+    onSearchChange?: (value: string) => void;
+    /** Accessible label for the search input. Defaults to English. */
+    searchLabel?: string;
+    /**
+     * Caller-defined Suggested category contents/order (unified or custom
+     * IDs). While present, `suggestedEmojisMode` is ignored for contents.
+     */
+    suggestedEmojis?: string[];
+    /** Observes compact-reactions vs full-picker transitions. */
+    onReactionsModeChange?: (reactionsOpen: boolean) => void;
+    /**
+     * Localized user-facing strings. Takes precedence over the individual
+     * `searchPlaceholder` / `searchLabel` / `searchClearButtonLabel` props.
+     */
+    labels?: Partial<PickerLabels>;
+    /**
+     * Controlled active skin tone. Pair with `onSkinToneChange`; while
+     * present, `defaultSkinTone` is ignored.
+     */
+    skinTone?: SkinTonesValue;
+    /**
+     * Emit the picker's CSS inside this cascade layer (e.g. "epr"), for
+     * layered CSS frameworks such as Tailwind v4 whose utilities cannot
+     * beat unlayered CSS. Declare the layer first in your CSS:
+     * `@layer epr, theme, base, components, utilities;`. Default: unlayered.
+     */
+    cssLayer?: string;
+    /**
+     * Emojis per row. The picker then sizes its width to fit those columns
+     * unless you set a width; a narrower container shows fewer columns.
+     * Default: as many as the width fits.
+     */
+    columns?: number;
+};
+type PreviewConfig = {
+    defaultEmoji: string;
+    defaultCaption: string;
+    showPreview: boolean;
+};
+type ConfigExternal = {
+    previewConfig: Partial<PreviewConfig>;
+    onEmojiClick: MouseDownEvent;
+    onReactionClick: MouseDownEvent;
+    onSkinToneChange: OnSkinToneChange;
+    /**
+     * User-supplied allowlist/order/merge input. Bare `Categories` members
+     * are accepted alongside full configs (as in v4 usage and this repo's
+     * own tests); the merged internal representation stays `CategoriesConfig`.
+     */
+    categories: UserCategoryConfig;
+    /**
+     * Dataset: an object (synchronous, SSR-safe), or a loader such as
+     * `() => import('emoji-picker-react/data/emojis-fr')` to code-split it.
+     * Omitted: the bundled English dataset.
+     */
+    emojiData: EmojiDataInput;
+} & Omit<PickerConfigInternal, 'previewConfig' | 'unicodeToHide' | 'categories' | 'emojiData'>;
+type PickerConfig = Partial<ConfigExternal>;
+type PickerDimensions = string | number;
+type MouseDownEvent = (emoji: EmojiClickData, event: MouseEvent, api?: OnEmojiClickApi) => void;
+type OnSkinToneChange = (skinTone: SkinTones) => void;
+/** The `onEmojiClick` / `onReactionClick` callback signature. */
+type EmojiClickHandler = MouseDownEvent;
+/** The `onSkinToneChange` callback signature. */
+type SkinToneChangeHandler = OnSkinToneChange;
+/** Third argument of `onEmojiClick` / `onReactionClick`. */
+type OnEmojiClickApi = {
+    /** Return to the compact reactions bar (no-op when reactions are off). */
+    collapseToReactions: () => void;
+};
+
+/** The emoji a custom `Emoji` cell renders. */
+type ListEmoji = {
+    /** True while hovered or keyboard-focused. */
+    isActive: boolean;
+    /** Unified code including the active skin tone, e.g. `1f44d-1f3fd`. */
+    unified: string;
+    names: string[];
+    /** Native emoji text (custom emojis: their id). */
+    emoji: string;
+    isCustom: boolean;
+    /** Active image style URL, or undefined for standard native emojis. */
+    imageUrl?: string;
+    /** Whether a long press opens skin tone variations. */
+    hasVariations: boolean;
+};
+/**
+ * Props for a custom emoji cell. Spread everything except `emoji` onto a
+ * `<button>`: the library-owned attributes (type, class, position style,
+ * tabIndex, aria-label, data-epr-*) carry selection, keyboard navigation,
+ * virtualization and accessibility. `children` is the default glyph/image;
+ * render it or your own content.
+ */
+type EmojiRenderProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    emoji: ListEmoji;
+    children: React.ReactNode;
+};
+/**
+ * Props for a custom category header. Spread everything except `category`
+ * onto the header element; it stays sticky and measured.
+ */
+type CategoryHeaderRenderProps = React.HTMLAttributes<HTMLElement> & {
+    category: {
+        id: string;
+        name: string;
+    };
+    children: React.ReactNode;
+};
+type ListComponents = {
+    Emoji?: React.ComponentType<EmojiRenderProps>;
+    CategoryHeader?: React.ComponentType<CategoryHeaderRenderProps>;
+};
+
+/** Spread the managed props onto one native button. Render children or your own content. */
+type CategoryButtonRenderProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    category: {
+        id: string;
+        name: string;
+        isActive: boolean;
+    };
+};
+type SkinToneButtonRenderProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    tone: {
+        skinTone: SkinTones;
+        isActive: boolean;
+        isOpen: boolean;
+    };
+};
+type PickerComponents = ListComponents & {
+    CategoryButton?: React.ComponentType<CategoryButtonRenderProps>;
+    SkinToneButton?: React.ComponentType<SkinToneButtonRenderProps>;
+    ExpandButton?: React.ComponentType<React.ButtonHTMLAttributes<HTMLButtonElement>>;
+    ClearButton?: React.ComponentType<React.ButtonHTMLAttributes<HTMLButtonElement>>;
+};
+
+declare function ExportedEmoji({ unified, size, emojiStyle, lazyLoad, getEmojiUrl, emojiUrl, }: {
+    unified: string;
+    emojiStyle?: EmojiStyleValue;
+    size?: number;
+    lazyLoad?: boolean;
+    getEmojiUrl?: GetEmojiUrl;
+    emojiUrl?: string;
+}): React.JSX.Element | null;
+
+declare function emojiByUnified(unified?: string): DataEmoji | undefined;
+
+interface PickerProps extends PickerConfig, React.AriaAttributes, Pick<React.HTMLAttributes<HTMLElement>, 'id' | 'title' | 'lang' | 'dir'> {
+    /**
+     * Color scheme: 'light' | 'dark' | 'auto'. Preferred over `theme`, which
+     * Emotion, styled-components and MUI reserve on components they wrap
+     * (a styled(EmojiPicker) would swallow it). `theme` remains supported.
+     */
+    colorScheme?: ThemeValue;
+    /**
+     * Render without decorative styling on every managed part.
+     * Geometry, presence and navigation remain managed. Style it with `className`,
+     * `--epr-*` variables and `[data-epr-part]` selectors.
+     */
+    unstyled?: boolean;
+    /** Shared replacements for interactive controls and category headers. */
+    components?: PickerComponents;
+}
+type Props = PickerProps;
+declare function EmojiPicker(props: PickerProps): React.JSX.Element;
+
+export { Categories, ExportedEmoji as Emoji, EmojiStyle, SkinTonePickerLocation, SkinTones, SuggestionMode, Theme, EmojiPicker as default, emojiByUnified };
+export type { CategoryButtonRenderProps, CategoryConfig, CategoryHeaderRenderProps, CategoryIcons, CustomEmoji, EmojiClickData, EmojiClickHandler, EmojiData, EmojiDataInput, EmojiDataLoader, EmojiDataLoaderOptions, EmojiRenderProps, EmojiStyleValue, ListComponents, ListEmoji, OnEmojiClickApi, PickerComponents, PickerLabels, PickerProps, PreviewConfig, Props, SkinToneButtonRenderProps, SkinToneChangeHandler, SkinTonesValue, SuggestionModeValue, ThemeValue };