emoji-picker-react 4.21.1 → 4.22.1

package/dist/hooks/useActiveCategoryScrollDetection.d.ts

@@ -1,4 +1,11 @@
-export declare function useActiveCategoryScrollDetection({ setActiveCategory, setVisibleCategories, }: {
+export declare function useActiveCategoryScrollDetection({ setActiveCategory, setVisibleCategories, categoryIdentitiesKey, }: {
     setActiveCategory: (category: string) => void;
     setVisibleCategories: (categories: string[]) => void;
+    /**
+     * Stable string derived from the rendered category identities
+     * (e.g. ids joined). Re-subscribes the observer when sections are
+     * added or removed so new elements are observed and detached ones
+     * stop contributing; unrelated renders keep the same key.
+     */
+    categoryIdentitiesKey: string;
 }): void;

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,42 @@ 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:
+
+### Updating groups at runtime
+
+`categories` and `customEmojis` are immutable inputs: replacing either
+array (even with a same-length array) rebuilds sections, tabs, search,
+and lookup. Mutating an array in place is not detected — always provide
+a new reference. Group strings are exact, case-sensitive identifiers.
+
+```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 +337,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.1",
+  "version": "4.22.1",
   "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/PickerConfigContext.tsx

@@ -39,7 +39,11 @@ export function useSetConfig(config: PickerConfig) {
     // not gonna...
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
-    config.customEmojis?.length,
+    // New references rebuild merged categories and data even at equal
+    // length; compareConfig above still gates no-op updates so inline
+    // literals don't loop.
+    config.categories,
+    config.customEmojis,
     config.open,
     config.emojiVersion,
     config.reactionsDefaultOpen,

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;
 }
@@ -33,8 +34,9 @@ export interface PickerDataContextValue {
 const PickerDataContext = React.createContext<PickerDataContextValue>({
   emojiData: {} as EmojiData,
   allEmojis: [],
-  allEmojisByUnified: {},
-  searchIndex: {},
+  allEmojisByUnified: Object.create(null),
+  searchIndex: Object.create(null),
+  customGroups: Object.create(null),
   emojiByUnified,
   activeVariationFromUnified: () => null,
 });
@@ -52,16 +54,34 @@ export function PickerDataProvider({
     // Clone to avoid mutation of shared source
     const newData: EmojiData = JSON.parse(JSON.stringify(emojiData));
 
+    // Group names and emoji ids are user-controlled strings: use
+    // null-prototype dictionaries so names like `__proto__` behave as
+    // ordinary data instead of resolving Object.prototype members.
+    const customGroups: Record<string, DataEmojis> = Object.create(null);
+
     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 allEmojisByUnified: Record<string, DataEmoji> = {};
-    const searchIndex: Record<string, Record<string, DataEmoji>> = {};
+    const allEmojis: DataEmojis = Object.values(emojis)
+      .concat(Object.values(customGroups))
+      .flat();
+    const allEmojisByUnified: Record<string, DataEmoji> =
+      Object.create(null);
+    const searchIndex: Record<string, Record<string, DataEmoji>> =
+      Object.create(null);
 
     allEmojis.forEach((emoji) => {
       const unified = emoji[Keys.unified];
@@ -81,7 +101,7 @@ export function PickerDataProvider({
         .split('');
 
       joinedNameString.forEach((char: string) => {
-        searchIndex[char] = searchIndex[char] ?? {};
+        searchIndex[char] = searchIndex[char] ?? Object.create(null);
         searchIndex[char][unified] = emoji;
       });
     });
@@ -91,6 +111,7 @@ export function PickerDataProvider({
       allEmojis,
       allEmojisByUnified,
       searchIndex,
+      customGroups,
     };
   }, [genericEmojiData, customEmojis]);
 
@@ -124,7 +145,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 +172,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';
 
@@ -23,18 +28,40 @@ export function CategoryNavigation() {
   const [activeCategory, setActiveCategory] = useState<string | null>(null);
   const [, setVisibleCategories] = useVisibleCategoriesState();
   const scrollCategoryIntoView = useScrollCategoryIntoView();
-  useActiveCategoryScrollDetection({ setActiveCategory, setVisibleCategories });
   const isSearchMode = useIsSearchMode();
 
   const categoriesConfig = useCategoriesConfig();
   const categoryIcons = useCategoryIconsConfig();
   const CategoryNavigationRef = useCategoryNavigationRef();
   const hideCustomCategory = useShouldHideCustomEmojis();
+  const { customGroups, emojiData } = usePickerDataContext();
 
-  const visibleCategories = categoriesConfig.filter(
-    categoryConfig =>
-      !(isCustomCategory(categoryConfig) && hideCustomCategory),
-  );
+  // Rendered section identities. Passed to the scroll-detection hook so
+  // added/removed sections are (re-)subscribed; stable across renders
+  // unless the effective category list changes.
+  const categoryIdentitiesKey = categoriesConfig
+    .map(entry => categoryIdFromCategoryConfig(entry))
+    .join('|');
+  useActiveCategoryScrollDetection({
+    setActiveCategory,
+    setVisibleCategories,
+    categoryIdentitiesKey,
+  });
+
+  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 +79,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/compareConfig.ts

@@ -1,4 +1,6 @@
+import { UserCategoryConfig } from './categoryConfig';
 import { PickerConfig } from './config';
+import { CustomEmoji } from './customEmojiConfig';
 
 // eslint-disable-next-line complexity
 export function compareConfig(prev: PickerConfig, next: PickerConfig) {
@@ -25,6 +27,35 @@ export function compareConfig(prev: PickerConfig, next: PickerConfig) {
     prev.searchDisabled === next.searchDisabled &&
     prev.skinTonePickerLocation === next.skinTonePickerLocation &&
     prevCustomEmojis.length === nextCustomEmojis.length &&
+    customEmojisKey(prevCustomEmojis) === customEmojisKey(nextCustomEmojis) &&
+    categoriesKey(prev.categories) === categoriesKey(next.categories) &&
     prev.emojiData === next.emojiData
   );
 }
+
+/**
+ * Content identity for custom emojis. Length alone misses regroups and
+ * swaps, which would leave merged categories, search, and sections stale.
+ */
+function customEmojisKey(customEmojis: CustomEmoji[]): string {
+  return customEmojis
+    .map(
+      emoji =>
+        `${emoji.id}:${emoji.group ?? ''}:${emoji.names.join(',')}:${emoji.imgUrl}`,
+    )
+    .join('|');
+}
+
+/**
+ * Content identity for the categories input. Order, labels, icons, and
+ * group selection all flow into the merged configuration.
+ */
+function categoriesKey(categories: UserCategoryConfig | undefined): string {
+  return (categories ?? [])
+    .map(entry =>
+      typeof entry === 'string'
+        ? entry
+        : `${entry.category}:${entry.name}:${entry.group ?? ''}:${entry.icon ? '1' : ''}`,
+    )
+    .join('|');
+}

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/useActiveCategoryScrollDetection.ts

@@ -7,9 +7,17 @@ import { useBodyRef } from '../components/context/ElementRefContext';
 export function useActiveCategoryScrollDetection({
   setActiveCategory,
   setVisibleCategories,
+  categoryIdentitiesKey,
 }: {
   setActiveCategory: (category: string) => void;
   setVisibleCategories: (categories: string[]) => void;
+  /**
+   * Stable string derived from the rendered category identities
+   * (e.g. ids joined). Re-subscribes the observer when sections are
+   * added or removed so new elements are observed and detached ones
+   * stop contributing; unrelated renders keep the same key.
+   */
+  categoryIdentitiesKey: string;
 }) {
   const BodyRef = useBodyRef();
 
@@ -67,5 +75,5 @@ export function useActiveCategoryScrollDetection({
     return () => {
       observer.disconnect();
     };
-  }, [BodyRef, setActiveCategory, setVisibleCategories]);
+  }, [BodyRef, categoryIdentitiesKey, setActiveCategory, setVisibleCategories]);
 }

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>>;