emoji-picker-react 4.21.0 → 4.22.0

package/dist/types/exposedTypes.d.ts

@@ -13,6 +13,12 @@ export declare 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;
 };
 export declare type CategoryIcons = Partial<Record<Categories, React.ReactNode>>;
 export declare type EmojiData = {

package/llms.txt

@@ -209,6 +209,7 @@ Pass the `customEmojis` prop to inject image-based emojis. Each entry uses this
   id: string;      // Unique ID
   names: string[]; // Search keywords
   imgUrl: string;  // Image source
+  group?: string;  // Optional section; see grouping below
 }
 ```
 
@@ -224,6 +225,35 @@ Pass the `customEmojis` prop to inject image-based emojis. Each entry uses this
 />
 ```
 
+### Grouping custom emojis
+
+Give customs a `group` to render each group as its own named section.
+Reference the group from a `{ category: Categories.CUSTOM, group }`
+entry in `categories` to place it anywhere in the order, with its own
+`name` and `icon`. Customs without a group share the classic bucket.
+Groups missing from `categories` are appended as their own sections
+automatically (after the standard categories), so grouped emojis always
+render somewhere. Omit `CUSTOM` from `categories` entirely to hide all
+customs — explicit `categories` stay an allowlist:
+
+```tsx
+import EmojiPicker, { Categories } from 'emoji-picker-react';
+
+<EmojiPicker
+  customEmojis={[
+    { id: 'panda', names: ['panda'], imgUrl: pandaPng, group: 'animals' },
+    { id: 'ninja', names: ['ninja'], imgUrl: ninjaPng, group: 'people' },
+    { id: 'orphan', names: ['orphan'], imgUrl: orphanPng },
+  ]}
+  categories={[
+    Categories.SMILEYS_PEOPLE,
+    { category: Categories.CUSTOM, group: 'animals', name: 'Animals' },
+    { category: Categories.CUSTOM, group: 'people', name: 'People' },
+    { category: Categories.CUSTOM, name: 'Misc' },
+  ]}
+/>;
+```
+
 ## Preview Bar
 
 Control the footer preview area with `previewConfig`:
@@ -300,7 +330,7 @@ import EmojiPicker, { Categories } from 'emoji-picker-react';
 />;
 ```
 
-Note: if both methods are used for the same category, the icon from the `categories` configuration takes precedence over the `categoryIcons` prop.
+Note: if both methods are used for the same category, the icon from the `categories` configuration takes precedence over the `categoryIcons` prop. `categoryIcons[Categories.CUSTOM]` applies to every custom group tab that does not define its own `icon`.
 
 ## Content Security Policy (CSP)
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.21.0",
+  "version": "4.22.0",
   "license": "MIT",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",

package/src/components/body/EmojiCategory.tsx

@@ -8,7 +8,7 @@ import {
   stylesheet,
 } from '../../Stylesheet/stylesheet';
 import {
-  categoryFromCategoryConfig,
+  categoryIdFromCategoryConfig,
   categoryNameFromCategoryConfig,
 } from '../../config/categoryConfig';
 import { CategoryConfig } from '../../types/exposedTypes';
@@ -30,7 +30,6 @@ export function EmojiCategory({
   height,
   emojisPerRow,
 }: Props) {
-  const category = categoryFromCategoryConfig(categoryConfig);
   const categoryName = categoryNameFromCategoryConfig(categoryConfig);
 
   return (
@@ -40,7 +39,7 @@ export function EmojiCategory({
         hidden && commonStyles.hidden,
         hiddenOnSearch && commonInteractionStyles.hiddenOnSearch,
       )}
-      data-name={category}
+      data-name={categoryIdFromCategoryConfig(categoryConfig)}
       role="rowgroup"
       aria-label={categoryName}
     >

package/src/components/body/EmojiList.tsx

@@ -4,7 +4,11 @@ import { cx } from 'shipstyles';
 import { ClassNames } from '../../DomUtils/classNames';
 import { getLabelHeight } from '../../DomUtils/elementPositionInRow';
 import { stylesheet } from '../../Stylesheet/stylesheet';
-import { categoryFromCategoryConfig } from '../../config/categoryConfig';
+import {
+  categoryFromCategoryConfig,
+  categoryIdFromCategoryConfig,
+  customGroupFromCategoryConfig,
+} from '../../config/categoryConfig';
 import { useCategoriesConfig } from '../../config/useConfig';
 import { DataEmojis } from '../../dataUtils/DataTypes';
 import { useEmojiVirtualization } from '../../hooks/useEmojiVirtualization';
@@ -41,25 +45,27 @@ export function EmojiList({ scrollTop }: { scrollTop: number }) {
       <MeasureEmoji />
       {categories.map((categoryConfig, index) => {
         const category = categoryFromCategoryConfig(categoryConfig);
+        const categoryId = categoryIdFromCategoryConfig(categoryConfig);
+        const group = customGroupFromCategoryConfig(categoryConfig);
 
         const currentOffset = topOffset;
-        const categoryHeight = categoryHeights[category];
+        const categoryHeight = categoryHeights[categoryId];
         if (categoryHeight) {
           topOffset += categoryHeight + labelHeight;
         }
 
         return (
           <RenderCategory
-            key={category}
-            categoryEmojis={getEmojisByCategory(category)}
+            key={categoryId}
+            categoryEmojis={getEmojisByCategory(category, group)}
             categoryConfig={categoryConfig}
             topOffset={currentOffset}
             isFirstCategory={index === 0}
             onHeightReady={(height) => {
-              if (categoryHeights[category] !== height) {
+              if (categoryHeights[categoryId] !== height) {
                 setCategoryHeights((prev) => ({
                   ...prev,
-                  [category]: height,
+                  [categoryId]: height,
                 }));
               }
             }}
@@ -95,7 +101,10 @@ function RenderCategory({
   // https://github.com/ealush/emoji-picker-react/issues/469
   // https://github.com/ealush/emoji-picker-react/issues/475
   const isCategoryVisible =
-    isFirstCategory || visibleCategories.includes(categoryConfig.category);
+    isFirstCategory ||
+    visibleCategories.includes(
+      categoryIdFromCategoryConfig(categoryConfig),
+    );
 
   const { virtualizedCounter, emojis, dimensions } = useEmojiVirtualization({
     categoryEmojis,

package/src/components/body/MeasureEmoji.tsx

@@ -1,6 +1,9 @@
 import * as React from 'react';
 
-import { categoryFromCategoryConfig } from '../../config/categoryConfig';
+import {
+  categoryFromCategoryConfig,
+  customGroupFromCategoryConfig,
+} from '../../config/categoryConfig';
 import {
   useCategoriesConfig,
   useEmojiStyleConfig,
@@ -37,9 +40,12 @@ export function MeasureEmoji() {
   }
 
   const firstCategory = categories[0];
-  const dummyEmoji = getEmojisByCategory(
-    categoryFromCategoryConfig(firstCategory),
-  )[0];
+  const dummyEmoji = firstCategory
+    ? getEmojisByCategory(
+        categoryFromCategoryConfig(firstCategory),
+        customGroupFromCategoryConfig(firstCategory),
+      )[0]
+    : undefined;
   const unified = dummyEmoji ? emojiUnified(dummyEmoji, activeSkinTone) : '';
 
   if (!dummyEmoji) {

package/src/components/context/PickerDataContext.tsx

@@ -26,6 +26,7 @@ export interface PickerDataContextValue {
   allEmojis: DataEmojis;
   allEmojisByUnified: Record<string, DataEmoji>;
   searchIndex: Record<string, Record<string, DataEmoji>>;
+  customGroups: Record<string, DataEmojis>;
   emojiByUnified: (unified?: string) => DataEmoji | undefined;
   activeVariationFromUnified: (unified: string) => SkinTones | null;
 }
@@ -35,6 +36,7 @@ const PickerDataContext = React.createContext<PickerDataContextValue>({
   allEmojis: [],
   allEmojisByUnified: {},
   searchIndex: {},
+  customGroups: {},
   emojiByUnified,
   activeVariationFromUnified: () => null,
 });
@@ -52,14 +54,27 @@ export function PickerDataProvider({
     // Clone to avoid mutation of shared source
     const newData: EmojiData = JSON.parse(JSON.stringify(emojiData));
 
+    const customGroups: Record<string, DataEmojis> = {};
+
     if (customEmojis && customEmojis.length > 0) {
-      newData.emojis[Categories.CUSTOM] =
-        customEmojis.map(customToRegularEmoji);
+      for (const emoji of customEmojis) {
+        if (!emoji.group) {
+          continue;
+        }
+        customGroups[emoji.group] = customGroups[emoji.group] ?? [];
+        customGroups[emoji.group].push(customToRegularEmoji(emoji));
+      }
+
+      newData.emojis[Categories.CUSTOM] = customEmojis
+        .filter(emoji => !emoji.group)
+        .map(customToRegularEmoji);
     }
 
     const emojis = newData.emojis || {};
 
-    const allEmojis: DataEmojis = Object.values(emojis).flat();
+    const allEmojis: DataEmojis = Object.values(emojis)
+      .concat(Object.values(customGroups))
+      .flat();
     const allEmojisByUnified: Record<string, DataEmoji> = {};
     const searchIndex: Record<string, Record<string, DataEmoji>> = {};
 
@@ -91,6 +106,7 @@ export function PickerDataProvider({
       allEmojis,
       allEmojisByUnified,
       searchIndex,
+      customGroups,
     };
   }, [genericEmojiData, customEmojis]);
 
@@ -124,7 +140,7 @@ export function usePickerDataContext() {
 }
 
 export function useGetEmojisByCategory() {
-  const { emojiData, emojiByUnified } = usePickerDataContext();
+  const { emojiData, emojiByUnified, customGroups } = usePickerDataContext();
   const suggestedEmojisModeConfig = useSuggestedEmojisModeConfig();
   const [suggestedUpdated] = useUpdateSuggested();
   // Suggestions come from localStorage, which doesn't exist during SSR.
@@ -151,11 +167,18 @@ export function useGetEmojisByCategory() {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isMounted, suggestedUpdated, suggestedEmojisModeConfig, emojiByUnified]);
 
-  return function getEmojisByCategory(category: Categories): DataEmojis {
+  return function getEmojisByCategory(
+    category: Categories,
+    group?: string,
+  ): DataEmojis {
     if (category === Categories.SUGGESTED) {
       return suggested;
     }
 
+    if (category === Categories.CUSTOM && group) {
+      return customGroups[group] ?? [];
+    }
+
     return emojiData.emojis?.[category] ?? [];
   };
 }

package/src/components/navigation/CategoryNavigation.tsx

@@ -3,7 +3,11 @@ import { useState } from 'react';
 import { cx } from 'shipstyles';
 
 import { stylesheet } from '../../Stylesheet/stylesheet';
-import { categoryFromCategoryConfig } from '../../config/categoryConfig';
+import {
+  categoryFromCategoryConfig,
+  categoryIdFromCategoryConfig,
+  customGroupFromCategoryConfig,
+} from '../../config/categoryConfig';
 import {
   useCategoriesConfig,
   useCategoryIconsConfig,
@@ -16,6 +20,7 @@ import { isCustomCategory } from '../../typeRefinements/typeRefinements';
 import { Categories } from '../../types/exposedTypes';
 import { useCategoryNavigationRef } from '../context/ElementRefContext';
 import { useVisibleCategoriesState } from '../context/PickerContext';
+import { usePickerDataContext } from '../context/PickerDataContext';
 
 import { CategoryButton } from './CategoryButton';
 
@@ -30,11 +35,22 @@ export function CategoryNavigation() {
   const categoryIcons = useCategoryIconsConfig();
   const CategoryNavigationRef = useCategoryNavigationRef();
   const hideCustomCategory = useShouldHideCustomEmojis();
+  const { customGroups, emojiData } = usePickerDataContext();
 
-  const visibleCategories = categoriesConfig.filter(
-    categoryConfig =>
-      !(isCustomCategory(categoryConfig) && hideCustomCategory),
-  );
+  const visibleCategories = categoriesConfig.filter(categoryConfig => {
+    if (isCustomCategory(categoryConfig) && hideCustomCategory) {
+      return false;
+    }
+    // Tabs navigating to an empty (hidden) section are dead weight.
+    const group = customGroupFromCategoryConfig(categoryConfig);
+    if (group) {
+      return (customGroups[group]?.length ?? 0) > 0;
+    }
+    if (isCustomCategory(categoryConfig)) {
+      return (emojiData.emojis?.[Categories.CUSTOM]?.length ?? 0) > 0;
+    }
+    return true;
+  });
 
   // A single tab navigates nowhere — hide the bar to reclaim its space.
   // https://github.com/ealush/emoji-picker-react/issues/396
@@ -52,22 +68,23 @@ export function CategoryNavigation() {
     >
       {visibleCategories.map(categoryConfig => {
         const category = categoryFromCategoryConfig(categoryConfig);
-        const isActiveCategory = category === activeCategory;
+        const categoryId = categoryIdFromCategoryConfig(categoryConfig);
+        const isActiveCategory = categoryId === activeCategory;
 
         const allowNavigation = !isSearchMode && !isActiveCategory;
 
         return (
           <CategoryButton
-            key={category}
+            key={categoryId}
             category={category}
             isActiveCategory={isActiveCategory}
             allowNavigation={allowNavigation}
             categoryConfig={categoryConfig}
             customIcon={categoryIcons[category as Categories]}
             onClick={() => {
-              scrollCategoryIntoView(category);
+              scrollCategoryIntoView(categoryId);
               setTimeout(() => {
-                setActiveCategory(category);
+                setActiveCategory(categoryId);
               }, 10);
             }}
           />

package/src/config/categoryConfig.ts

@@ -5,6 +5,8 @@ import {
   SuggestionMode,
 } from '../types/exposedTypes';
 
+import { CustomEmoji } from './customEmojiConfig';
+
 export { Categories };
 
 const categoriesOrdered: Categories[] = [
@@ -28,8 +30,52 @@ export const SuggestedRecent: CategoryConfig = {
 export type CustomCategoryConfig = {
   category: Categories.CUSTOM;
   name: string;
+  /**
+   * Selects the `CustomEmoji` group rendered in this section. Each entry
+   * may carry its own `name` and `icon`, so multiple custom sections can
+   * coexist — each placed wherever its entry sits in `categories`.
+   * Entries without a group share the ungrouped customs bucket.
+   */
+  group?: string;
 };
 
+/**
+ * Stable identity for a category entry. Custom groups are namespaced so
+ * duplicate `{ category: CUSTOM }` configs no longer collide in React
+ * keys, scroll targets, and active-tab detection.
+ */
+export function categoryIdFromCategoryConfig(
+  categoryConfig: CategoryConfig,
+): string {
+  const category = categoryFromCategoryConfig(categoryConfig);
+  if (isCustomGroupConfig(categoryConfig)) {
+    return `${category}:${categoryConfig.group}`;
+  }
+  return category;
+}
+
+function isCustomGroupConfig(
+  categoryConfig: CategoryConfig,
+): categoryConfig is CustomCategoryConfig & { group: string } {
+  if (categoryConfig.category !== Categories.CUSTOM) {
+    return false;
+  }
+  const group = (categoryConfig as CustomCategoryConfig).group;
+  return typeof group === 'string' && group.length > 0;
+}
+
+/**
+ * The `CustomEmoji` group rendered by a category entry, if any.
+ */
+export function customGroupFromCategoryConfig(
+  categoryConfig: CategoryConfig,
+): string | undefined {
+  if (isCustomGroupConfig(categoryConfig)) {
+    return categoryConfig.group;
+  }
+  return undefined;
+}
+
 const configByCategory: Record<Categories, CategoryConfig> = {
   [Categories.SUGGESTED]: {
     category: Categories.SUGGESTED,
@@ -100,6 +146,7 @@ export function mergeCategoriesConfig(
   userCategoriesConfig: UserCategoryConfig = [],
   modifiers: CategoryConfigModifiers = {},
   emojiData?: EmojiData,
+  customEmojis: CustomEmoji[] = [],
 ): CategoriesConfig {
   const extra = ((): Record<Categories, CategoryConfig> => {
     // 1. Start with localized categories from emojiData
@@ -124,11 +171,56 @@ export function mergeCategoriesConfig(
 
   const base = baseCategoriesConfig(extra);
 
-  if (!userCategoriesConfig?.length) {
-    return base;
-  }
+  const explicit: CategoriesConfig = userCategoriesConfig?.length
+    ? userCategoriesConfig.map(mapUserEntry)
+    : base;
+
+  // Groups without a `categories` entry get an appended section so their
+  // emojis always render somewhere — unless the user opted out of customs
+  // entirely by listing `categories` without CUSTOM. `categories` remains
+  // the override for order, display name, and icon.
+  // https://github.com/ealush/emoji-picker-react/issues/510
+  const customInPlay =
+    !userCategoriesConfig?.length ||
+    userCategoriesConfig.some(
+      entry =>
+        entry === Categories.CUSTOM ||
+        (typeof entry !== 'string' && entry.category === Categories.CUSTOM),
+    );
+  const listedGroups = new Set(
+    explicit
+      .map(entry => customGroupFromCategoryConfig(entry))
+      .filter((group): group is string => !!group),
+  );
+  const appended: CategoriesConfig = !customInPlay
+    ? []
+    : Array.from(
+        new Set(
+          customEmojis
+            .map(emoji => emoji.group)
+            .filter((group): group is string => !!group),
+        ),
+      )
+        .filter(group => !listedGroups.has(group))
+        .map(group => ({
+          category: Categories.CUSTOM,
+          name: group,
+          group,
+        }));
+
+  // Collapse duplicate entries (same identity twice renders the same
+  // section twice under one React key); first occurrence wins.
+  const seen = new Set<string>();
+  return explicit.concat(appended).filter(entry => {
+    const id = categoryIdFromCategoryConfig(entry);
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
 
-  return userCategoriesConfig.map((category) => {
+  function mapUserEntry(category: Categories | CategoryConfig) {
     if (typeof category === 'string') {
       return getBaseConfigByCategory(category, extra[category]);
     }
@@ -137,7 +229,7 @@ export function mergeCategoriesConfig(
       ...getBaseConfigByCategory(category.category, extra[category.category]),
       ...category,
     };
-  });
+  }
 }
 
 function getBaseConfigByCategory(

package/src/config/config.ts

@@ -64,6 +64,7 @@ export function mergeConfig(
       suggestionMode: config.suggestedEmojisMode,
     },
     userConfig.emojiData,
+    userConfig.customEmojis,
   );
 
   config.hiddenEmojis.forEach((emoji) => {

package/src/config/customEmojiConfig.ts

@@ -4,4 +4,12 @@ export 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;
 };

package/src/hooks/useEmojiPreviewEvents.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { useEffect } from 'react';
 
+import { detectEmojyPartiallyBelowFold } from '../DomUtils/detectEmojyPartiallyBelowFold';
 import { focusElement } from '../DomUtils/focusElement';
 import {
   allUnifiedFromEmojiElement,
@@ -107,11 +108,25 @@ export function useEmojiPreviewEvents(
       // Pulling focus out of an external element steals the caret from
       // host-app inputs (issue #320). The guard runs again inside the
       // deferred callback in case focus moved out after this event.
-      if (!isExternalElementFocused()) {
+      // Partially visible buttons are never focused: focusing would make
+      // the browser scroll them into view, yanking the scroll position
+      // while the user is browsing (see also PR #509).
+      if (
+        !isExternalElementFocused() &&
+        !isPartiallyBelowFold(button, bodyRef)
+      ) {
         focusElement(button, () => !isExternalElementFocused());
       }
     }
 
+    function isPartiallyBelowFold(
+      button: HTMLButtonElement,
+      body: HTMLElement | null,
+    ): boolean {
+      const belowFoldByPx = detectEmojyPartiallyBelowFold(button, body);
+      return belowFoldByPx < button.getBoundingClientRect().height;
+    }
+
     function isExternalElementFocused(): boolean {
       const active = document.activeElement as HTMLElement | null;
 
@@ -129,5 +144,5 @@ export function useEmojiPreviewEvents(
       bodyRef?.removeEventListener('blur', onLeave, true);
       bodyRef?.removeEventListener('keydown', onEscape);
     };
-  }, [BodyRef, allow, setPreviewEmoji, isMouseDisallowed, allowMouseMove]);
+  }, [BodyRef, PickerMainRef, allow, setPreviewEmoji, isMouseDisallowed, allowMouseMove]);
 }

package/src/hooks/useScrollCategoryIntoView.ts

@@ -13,8 +13,9 @@ export function useScrollCategoryIntoView() {
     if (!BodyRef.current) {
       return;
     }
+    // Group names are user-controlled; escape for the attribute selector.
     const $category = BodyRef.current?.querySelector(
-      `[data-name="${category}"]`,
+      `[data-name="${CSS.escape(category)}"]`,
     ) as NullableElement;
 
     if (!$category) {

package/src/types/exposedTypes.ts

@@ -15,6 +15,12 @@ export 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;
 };
 
 export type CategoryIcons = Partial<Record<Categories, React.ReactNode>>;