feat: add custom emoji category support

CUSTOM-EMOJIS.md

@@ -0,0 +1,147 @@
+# Custom Emoji Support
+
+## Overview
+
+The `custom` prop on `<EmojiPicker.Root>` lets you inject image-based emoji categories into the picker. Custom categories appear after the standard Unicode emoji categories and are searchable by label and tags. The `frequently` prop adds a "Frequently Used" category at the top of the picker, supporting both native and custom emojis.
+
+## Usage
+
+Pass custom categories via the `custom` prop on `<EmojiPicker.Root>` and provide a custom `Emoji` component via `<EmojiPicker.List>` to render images:
+
+```tsx
+const customCategories = [
+  {
+    id: "team",
+    label: "Team",
+    emojis: [
+      { id: "shipit", label: "Ship It", url: "/emojis/shipit.png", tags: ["ship", "deploy"] },
+      { id: "lgtm", label: "Looks Good To Me", url: "/emojis/lgtm.png", tags: ["approve"] },
+    ],
+  },
+];
+
+function MyEmojiPicker() {
+  return (
+    <EmojiPicker.Root
+      custom={customCategories}
+      onEmojiSelect={(emoji) => {
+        if (emoji.url) {
+          // Handle custom image emoji
+          console.log("Custom emoji:", emoji.id, emoji.url);
+        } else {
+          // Handle standard Unicode emoji
+          console.log("Emoji:", emoji.emoji);
+        }
+      }}
+    >
+      <EmojiPicker.Search />
+      <EmojiPicker.Viewport>
+        <EmojiPicker.List
+          components={{
+            Emoji: ({ emoji, ...props }) => (
+              <button {...props}>
+                {emoji.url ? (
+                  <img src={emoji.url} alt={emoji.label} style={{ width: "1em", height: "1em" }} />
+                ) : (
+                  emoji.emoji
+                )}
+              </button>
+            ),
+          }}
+        />
+      </EmojiPicker.Viewport>
+    </EmojiPicker.Root>
+  );
+}
+```
+
+## Search
+
+Custom emojis are searchable using the same scoring as standard emojis:
+
+- **Label match**: +10 points
+- **Tag match**: +1 point per tag
+
+Results are sorted by score descending and filtered when using `<EmojiPicker.Search>`.
+
+### Unified Search
+
+By default, search results are displayed within their original categories (standard Unicode categories and custom categories separately). Enable `unifiedSearch` to merge all results — native and custom — into a single ranked list sorted by relevance score:
+
+```tsx
+<EmojiPicker.Root
+  custom={customCategories}
+  unifiedSearch
+  searchLabel="Results"
+  onEmojiSelect={handleSelect}
+>
+  {/* ... */}
+</EmojiPicker.Root>
+```
+
+- **`unifiedSearch`** (`boolean`, default `false`): When `true`, all search results are combined into one category ranked by score. Has no effect when there is no active search query.
+- **`searchLabel`** (`string`, optional): Label for the unified results category header. Defaults to `""` if omitted.
+
+## `onEmojiSelect` Handling
+
+The `emoji` object passed to `onEmojiSelect` differs for custom vs standard emojis:
+
+| Field   | Standard Emoji | Custom Emoji |
+| ------- | -------------- | ------------ |
+| `emoji` | `"😀"`         | `undefined`  |
+| `label` | `"Grinning"`   | `"Ship It"`  |
+| `url`   | `undefined`    | `"/emojis/shipit.png"` |
+| `id`    | `undefined`    | `"shipit"`   |
+
+Check for `emoji.url` to distinguish between the two.
+
+## Frequently Used Emojis
+
+Pass an array of `EmojiPickerEmoji` objects via the `frequently` prop to display a "Frequently Used" category at the top of the picker. Supports both native and custom emojis. The category is hidden during search.
+
+```tsx
+<EmojiPicker.Root
+  frequently={[
+    { emoji: "👍", label: "Thumbs Up" },
+    { emoji: "❤️", label: "Red Heart" },
+    { id: "shipit", label: "Ship It", url: "/emojis/shipit.png" },
+  ]}
+  frequentlyLabel="Favorites"
+  onEmojiSelect={handleSelect}
+>
+  {/* ... */}
+</EmojiPicker.Root>
+```
+
+The consumer is responsible for tracking and persisting frequency data — frimousse does not manage localStorage or usage counts internally.
+
+## Prop Reference
+
+All custom emoji props are added to `<EmojiPicker.Root>`:
+
+| Prop              | Type                  | Default             | Description |
+| ----------------- | --------------------- | ------------------- | ----------- |
+| `custom`          | `CustomCategory[]`    | —                   | Custom image-based emoji categories, appended after standard categories. |
+| `frequently`      | `EmojiPickerEmoji[]`  | —                   | Emojis to show in a "Frequently Used" category at the top. Hidden during search. |
+| `frequentlyLabel` | `string`              | `"Frequently Used"` | Label for the frequently used category header. |
+| `unifiedSearch`   | `boolean`             | `false`             | When `true`, merges all search results into one ranked list. |
+| `searchLabel`     | `string`              | `""`                | Category header label when `unifiedSearch` is active. |
+
+## Types
+
+```ts
+type CustomEmoji = {
+  id: string;
+  label: string;
+  url: string;
+  tags?: string[];
+};
+
+type CustomCategory = {
+  id: string;
+  label: string;
+  emojis: CustomEmoji[];
+};
+```
+
+Both are exported from `frimousse`.

src/components/emoji-picker.tsx

@@ -18,8 +18,10 @@ import {
   useState,
 } from "react";
 import { EMOJI_FONT_FAMILY } from "../constants";
+import type { CustomEmojiRootProps } from "../custom-emoji-types";
 import { getEmojiData, validateLocale, validateSkinTone } from "../data/emoji";
 import { getEmojiPickerData } from "../data/emoji-picker";
+import { loadShortcodes } from "../data/shortcodes";
 import { useActiveEmoji, useSkinTone } from "../hooks";
 import {
   $activeEmoji,
@@ -57,6 +59,7 @@ import type {
   WithAttributes,
 } from "../types";
 import { shallow } from "../utils/compare";
+import { isSameEmoji } from "../utils/emoji-identity";
 import { noop } from "../utils/noop";
 import { requestIdleCallback } from "../utils/request-idle-callback";
 import { useCreateStore, useSelector, useSelectorKey } from "../utils/store";
@@ -66,7 +69,15 @@ import { useStableCallback } from "../utils/use-stable-callback";
 function EmojiPickerDataHandler({
   emojiVersion,
   emojibaseUrl,
-}: Pick<EmojiPickerRootProps, "emojiVersion" | "emojibaseUrl">) {
+  custom,
+  frequently,
+  frequentlyLabel,
+  unifiedSearch,
+  searchLabel,
+}: Pick<
+  EmojiPickerRootProps & CustomEmojiRootProps,
+  "emojiVersion" | "emojibaseUrl" | "custom" | "frequently" | "frequentlyLabel" | "unifiedSearch" | "searchLabel"
+>) {
   const [emojiData, setEmojiData] = useState<EmojiData | undefined>(undefined);
   const store = useEmojiPickerStore();
   const locale = useSelectorKey(store, "locale");
@@ -78,6 +89,8 @@ function EmojiPickerDataHandler({
     const controller = new AbortController();
     const signal = controller.signal;
 
+    loadShortcodes(emojibaseUrl, emojiVersion).catch(() => {});
+
     getEmojiData({ locale, emojiVersion, emojibaseUrl, signal })
       .then((data) => {
         setEmojiData(data);
@@ -103,12 +116,12 @@ function EmojiPickerDataHandler({
         store
           .get()
           .onDataChange(
-            getEmojiPickerData(emojiData, columns, skinTone, search),
+            getEmojiPickerData(emojiData, columns, skinTone, search, custom, frequently, frequentlyLabel, unifiedSearch, searchLabel),
           );
       },
       { timeout: 100 },
     );
-  }, [emojiData, columns, skinTone, search]);
+  }, [emojiData, columns, skinTone, search, custom, frequently, frequentlyLabel, unifiedSearch, searchLabel]);
 
   return null;
 }
@@ -136,13 +149,18 @@ function EmojiPickerDataHandler({
  * </EmojiPicker.Root>
  * ```
  */
-const EmojiPickerRoot = forwardRef<HTMLDivElement, EmojiPickerRootProps>(
+const EmojiPickerRoot = forwardRef<HTMLDivElement, EmojiPickerRootProps & CustomEmojiRootProps>(
   (
     {
       locale = "en",
       columns = 9,
       skinTone = "none",
       onEmojiSelect = noop,
+      custom,
+      frequently,
+      frequentlyLabel,
+      unifiedSearch,
+      searchLabel,
       emojiVersion,
       emojibaseUrl,
       onFocusCapture,
@@ -472,6 +490,11 @@ const EmojiPickerRoot = forwardRef<HTMLDivElement, EmojiPickerRootProps>(
           <EmojiPickerDataHandler
             emojibaseUrl={emojibaseUrl}
             emojiVersion={emojiVersion}
+            custom={custom}
+            frequently={frequently}
+            frequentlyLabel={frequentlyLabel}
+            unifiedSearch={unifiedSearch}
+            searchLabel={searchLabel}
           />
           {children}
         </EmojiPickerStoreProvider>
@@ -840,9 +863,8 @@ const EmojiPickerListEmoji = memo(
     rowIndex: number;
   } & Pick<EmojiPickerListComponents, "Emoji">) => {
     const store = useEmojiPickerStore();
-    const isActive = useSelector(
-      store,
-      (state) => $activeEmoji(state)?.emoji === emoji.emoji,
+    const isActive = useSelector(store, (state) =>
+      isSameEmoji($activeEmoji(state), emoji),
     );
 
     const handleSelect = useCallback(() => {

src/custom-emoji-types.ts

@@ -0,0 +1,61 @@
+import type { EmojiPickerEmoji, EmojiPickerRootProps } from "./types";
+
+export type CustomEmoji = {
+  id: string;
+  label: string;
+  url: string;
+  tags?: string[];
+};
+
+export type CustomCategory = {
+  id: string;
+  label: string;
+  emojis: CustomEmoji[];
+};
+
+/**
+ * Additional root props for custom emoji support.
+ * Intersected with the upstream EmojiPickerRootProps at the component level.
+ */
+export interface CustomEmojiRootProps {
+  /**
+   * Custom emoji categories to append to the picker.
+   */
+  custom?: CustomCategory[];
+
+  /**
+   * Frequently used emojis to display at the top of the picker.
+   * Supports both native emojis (with `emoji` field) and custom emojis (with `url` and `id` fields).
+   */
+  frequently?: EmojiPickerEmoji[];
+
+  /**
+   * The label for the frequently used category header.
+   *
+   * @default "Frequently Used"
+   */
+  frequentlyLabel?: string;
+
+  /**
+   * When true, search results from both native and custom emojis are merged
+   * into a single flat category sorted by relevance, instead of being
+   * displayed within their original categories.
+   *
+   * @default false
+   */
+  unifiedSearch?: boolean;
+
+  /**
+   * The label for the unified search results category header.
+   * Only used when `unifiedSearch` is true.
+   *
+   * @default ""
+   */
+  searchLabel?: string;
+}
+
+/**
+ * Full root props type, including custom emoji extensions.
+ * Re-exported from index.ts as EmojiPickerRootProps to shadow the upstream type.
+ */
+export type AugmentedEmojiPickerRootProps = EmojiPickerRootProps & CustomEmojiRootProps;