refactor(emojis): slim down the StreamEmojiPicker public API

`StreamEmojiPicker` is unreleased and `emoji-mart` is back as a deprecated engine,
so its emoji-mart-shaped option surface is no longer needed. Replace the `pickerProps`
bag with a small set of flat props and drop the low-value knobs.

- Remove the `pickerProps` object and the `warnUnsupportedPickerProps` machinery
  (TypeScript now rejects unknown props); hoist the keepers to flat props: `theme`,
  `style`, `categories`, `exceptEmojis`, `autoFocus`, `onClickOutside`.
- Drop the layout/cosmetic/niche knobs (`perLine`, `navPosition`, `previewPosition`,
  `searchPosition`, `skinTonePosition`, `maxFrequentRows`, `previewEmoji`,
  `noResultsEmoji`, `emojiVersion`, `noCountryFlags`). The panel now uses one fixed
  layout and the column count is driven by the `--str-chat__emoji-picker-per-line`
  CSS token (default 9).
- Delete `options.ts` and `hooks/pickerLayout.ts`; simplify `filterEmojiData` to
  `exceptEmojis` only.
- Update the vite example (engine + auto-focus controls only), remove the now-dead
  SCSS, and refresh the AI.md emoji docs.

Skin-tone and frequently-used props and the shell customization props are unchanged.

Author: oliverlaz

AI.md

@@ -274,27 +274,16 @@ import 'stream-chat-react/css/emoji-picker.css';
 - On `StreamEmojiPicker`, skin tone and "frequently used" are integrator-managed props
   (`skinTone`/`onSkinToneChange`, `frequentlyUsedEmoji`/`onFrequentlyUsedChange`);
   the SDK does not persist them. See `examples/vite/` for a localStorage example.
-- On `StreamEmojiPicker`, `pickerProps` accepts a curated set of emoji-mart-compatible `Picker` options (plus
-  `theme` and `style`):
-  - **Layout**: `navPosition` / `previewPosition` (`'top' | 'bottom' | 'none'`),
-    `searchPosition` (`'sticky' | 'static' | 'none'`), `skinTonePosition`
-    (`'preview' | 'search' | 'none'`).
-  - **Grid & content**: `perLine` (default `9`), `categories` (filter + reorder;
-    `'frequent'` always prepends), `maxFrequentRows` (default `1`).
-  - **Filtering & polish**: `exceptEmojis`, `emojiVersion`, `noCountryFlags`,
-    `previewEmoji`, `noResultsEmoji`, `autoFocus`, `onClickOutside`.
-
-  Divergences from emoji-mart's defaults: `autoFocus` defaults to `true`; `emojiVersion`
-  is unfiltered by default (the bundled set 15); `previewEmoji` / `noResultsEmoji` default
-  to the SDK's placeholder / empty state; `noCountryFlags` is opt-in (no Windows
-  auto-detect); `categories` cannot reposition `'frequent'`.
-
-  Not supported (rejected by the type; ignored with a console warning at runtime): image
-  sets (`set`, `getSpritesheetURL`), `custom` emoji, `data`, `i18n` / `locale`,
-  `dynamicWidth`, `icons`, `categoryIcons`. Sizing knobs (`emojiSize`, `emojiButtonSize`,
-  …) are `--str-chat__emoji-picker-*` CSS variables, not props. Skin tone uses the
-  first-class `skinTone` / `defaultSkinTone` props (not emoji-mart's `skin`). Try these
-  live in the "Emoji Picker" settings tab of `examples/vite/`.
+- `StreamEmojiPicker` exposes a small, flat set of props (no emoji-mart-style
+  `pickerProps` bag): `theme` (`'auto'` — the default, inherits the ancestor SDK theme —
+  `'light'`, or `'dark'`), `style`, `categories` (filter + reorder; `'frequent'` always
+  prepends and cannot be repositioned), `exceptEmojis`, `autoFocus` (default `true`), and
+  `onClickOutside`. Layout and sizing are CSS, not props: set
+  `--str-chat__emoji-picker-per-line` (default `9`) for the column count and the other
+  `--str-chat__emoji-picker-*` tokens for sizing/colors. Emoji-mart-only features (image
+  `set`s, `custom` emoji, `data`, `i18n` / `locale`, …) aren't available on the built-in
+  picker — keep using the deprecated `EmojiPicker` if you still need them. Try it live in
+  the "Emoji Picker" settings tab of `examples/vite/`.
 
 - To let users **react with any emoji** (the reaction selector's `+` button), fill
   `reactionOptions.extended` with the full emoji set. It also gates display — a reaction
@@ -321,9 +310,11 @@ import 'stream-chat-react/css/emoji-picker.css';
 - **Migrating from emoji-mart** (the deprecated `EmojiPicker`): swap `EmojiPicker` →
   `StreamEmojiPicker`, then remove the `emoji-mart` / `@emoji-mart/react` /
   `@emoji-mart/data` installs and any `init({ data })` call. The deprecated `EmojiPicker`
-  still accepts raw emoji-mart `pickerProps` (e.g. `set`, `emojiSize`); `StreamEmojiPicker`
-  uses the curated `pickerProps` above. Autocomplete (`createTextComposerEmojiMiddleware`)
-  and reactions (`mapEmojiMartData`) are engine-agnostic and need no changes.
+  takes a raw emoji-mart `pickerProps` bag (e.g. `set`, `emojiSize`); `StreamEmojiPicker`
+  instead exposes flat props (`theme`, `categories`, `exceptEmojis`, `autoFocus`, …) and
+  moves layout/sizing to `--str-chat__emoji-picker-*` CSS tokens. Autocomplete
+  (`createTextComposerEmojiMiddleware`) and reactions (`mapEmojiMartData`) are
+  engine-agnostic and need no changes.
 
 **Reference**: See `examples/tutorial/src/6-emoji-picker/`
 

examples/vite/src/App.tsx

@@ -226,6 +226,7 @@ const EmojiPickerWithCustomOptions = (
   return (
     <StreamEmojiPicker
       {...props}
+      autoFocus={pickerOptions.autoFocus}
       frequentlyUsedEmoji={frequentlyUsedEmoji}
       onFrequentlyUsedChange={(ids) => {
         setFrequentlyUsedEmoji(ids);
@@ -235,12 +236,8 @@ const EmojiPickerWithCustomOptions = (
         setSkinTone(tone);
         writeStored(EMOJI_SKIN_TONE_KEY, tone);
       }}
-      pickerProps={{
-        ...props.pickerProps,
-        ...pickerOptions,
-        theme: mode,
-      }}
       skinTone={skinTone}
+      theme={mode}
     />
   );
 };

examples/vite/src/AppSettings/state.ts

@@ -14,26 +14,12 @@ export type ChatViewSettingsState = {
 export type EmojiPickerSettingsState = {
   autoFocus: boolean;
   engine: 'emoji-mart' | 'stream';
-  maxFrequentRows: number;
-  navPosition: 'top' | 'bottom' | 'none';
-  noCountryFlags: boolean;
-  perLine: number;
-  previewPosition: 'top' | 'bottom' | 'none';
-  searchPosition: 'sticky' | 'static' | 'none';
-  skinTonePosition: 'preview' | 'search' | 'none';
 };
 
 // Mirrors the SDK's EmojiPicker defaults; the settings tab resets to this.
 export const DEFAULT_EMOJI_PICKER_SETTINGS: EmojiPickerSettingsState = {
   autoFocus: true,
   engine: 'stream',
-  maxFrequentRows: 1,
-  navPosition: 'top',
-  noCountryFlags: false,
-  perLine: 9,
-  previewPosition: 'bottom',
-  searchPosition: 'sticky',
-  skinTonePosition: 'preview',
 };
 
 export type ThemeSettingsState = {

examples/vite/src/AppSettings/tabs/EmojiPicker/EmojiPickerTab.tsx

@@ -62,27 +62,23 @@ function Field<T extends string | number | boolean>({
   );
 }
 
-const numberOptions = (values: number[]) =>
-  values.map((value) => ({ label: String(value), value }));
-
 /**
  * Always-open picker wired to the current settings, so tweaks show instantly without
  * opening the composer. Skin tone and frequently-used are local to the preview —
- * selecting an emoji here feeds the "frequently used" row so `maxFrequentRows` can be
- * exercised too.
+ * selecting an emoji here feeds the "frequently used" row.
  */
 const EmojiPickerPreview = ({ options }: { options: EmojiPickerSettingsState }) => {
   const { mode } = useAppSettingsSelector((state) => state.theme);
-  const { engine, ...pickerOptions } = options;
+  const { autoFocus, engine } = options;
   const [skinTone, setSkinTone] = useState(0);
   const [frequentlyUsedIds, setFrequentlyUsedIds] = useState<string[]>([]);
 
-  // The deprecated emoji-mart picker renders inline too and honors the same
-  // emoji-mart-compatible option names, so the same controls drive both engines.
+  // The deprecated emoji-mart picker renders inline too and honors the same option
+  // names, so the shared controls drive both engines.
   if (engine === 'emoji-mart') {
     return (
       <EmojiMart
-        {...pickerOptions}
+        autoFocus={autoFocus}
         data={async () => (await import('@emoji-mart/data')).default}
         onEmojiSelect={() => undefined}
         theme={mode}
@@ -92,20 +88,20 @@ const EmojiPickerPreview = ({ options }: { options: EmojiPickerSettingsState })
 
   return (
     <EmojiPickerPanel
+      autoFocus={autoFocus}
       frequentlyUsedIds={frequentlyUsedIds}
       onEmojiSelect={(emoji: EmojiSelection) =>
         setFrequentlyUsedIds((ids) => [emoji.id, ...ids.filter((id) => id !== emoji.id)])
       }
       onSkinToneChange={setSkinTone}
-      options={{ ...pickerOptions, exceptEmojis: [] }}
       skinToneIndex={skinTone}
     />
   );
 };
 
 /**
- * Playground for the built-in EmojiPicker's `pickerProps`. Each control writes to the
- * app settings store; the live preview (and the composer's picker via
+ * Playground for the built-in `StreamEmojiPicker`. Each control writes to the app
+ * settings store; the live preview (and the composer's picker via
  * `EmojiPickerWithCustomOptions`) reflect the change instantly.
  */
 export const EmojiPickerTab = ({ close }: EmojiPickerTabProps) => {
@@ -118,7 +114,7 @@ export const EmojiPickerTab = ({ close }: EmojiPickerTabProps) => {
     <div className='app__settings-modal__content-stack'>
       <SettingsTabLayoutHeader
         close={close}
-        description='Switch between the Stream (native) and deprecated emoji-mart pickers, and configure pickerProps. The live preview and the composer’s picker both update instantly.'
+        description='Switch between the Stream (native) and deprecated emoji-mart pickers. The live preview and the composer’s picker both update instantly.'
         title='Emoji Picker'
       />
 
@@ -147,58 +143,6 @@ export const EmojiPickerTab = ({ close }: EmojiPickerTabProps) => {
               ]}
               value={emojiPicker.engine}
             />
-            <Field<EmojiPickerSettingsState['navPosition']>
-              label='Navigation position'
-              onSelect={(navPosition) => update({ navPosition })}
-              options={[
-                { label: 'Top', value: 'top' },
-                { label: 'Bottom', value: 'bottom' },
-                { label: 'None', value: 'none' },
-              ]}
-              value={emojiPicker.navPosition}
-            />
-            <Field<EmojiPickerSettingsState['previewPosition']>
-              label='Preview position'
-              onSelect={(previewPosition) => update({ previewPosition })}
-              options={[
-                { label: 'Top', value: 'top' },
-                { label: 'Bottom', value: 'bottom' },
-                { label: 'None', value: 'none' },
-              ]}
-              value={emojiPicker.previewPosition}
-            />
-            <Field<EmojiPickerSettingsState['searchPosition']>
-              label='Search position'
-              onSelect={(searchPosition) => update({ searchPosition })}
-              options={[
-                { label: 'Sticky', value: 'sticky' },
-                { label: 'Static', value: 'static' },
-                { label: 'None', value: 'none' },
-              ]}
-              value={emojiPicker.searchPosition}
-            />
-            <Field<EmojiPickerSettingsState['skinTonePosition']>
-              label='Skin-tone position'
-              onSelect={(skinTonePosition) => update({ skinTonePosition })}
-              options={[
-                { label: 'Preview', value: 'preview' },
-                { label: 'Search', value: 'search' },
-                { label: 'None', value: 'none' },
-              ]}
-              value={emojiPicker.skinTonePosition}
-            />
-            <Field<number>
-              label='Emoji per line'
-              onSelect={(perLine) => update({ perLine })}
-              options={numberOptions([7, 8, 9, 10])}
-              value={emojiPicker.perLine}
-            />
-            <Field<number>
-              label='Frequently-used rows'
-              onSelect={(maxFrequentRows) => update({ maxFrequentRows })}
-              options={numberOptions([1, 2, 3, 4])}
-              value={emojiPicker.maxFrequentRows}
-            />
             <Field<boolean>
               label='Auto-focus search'
               onSelect={(autoFocus) => update({ autoFocus })}
@@ -208,15 +152,6 @@ export const EmojiPickerTab = ({ close }: EmojiPickerTabProps) => {
               ]}
               value={emojiPicker.autoFocus}
             />
-            <Field<boolean>
-              label='Country flags'
-              onSelect={(noCountryFlags) => update({ noCountryFlags })}
-              options={[
-                { label: 'Show', value: false },
-                { label: 'Hide', value: true },
-              ]}
-              value={emojiPicker.noCountryFlags}
-            />
           </div>
           <div className='app__emoji-settings__preview'>
             <div className='app__settings-modal__field-label'>Live preview</div>

src/plugins/Emojis/StreamEmojiPicker.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef, useState } from 'react';
+import React, { type CSSProperties, useEffect, useRef, useState } from 'react';
 
 import { useMessageComposerContext, useTranslationContext } from '../../context';
 import {
@@ -12,46 +12,29 @@ import { useIsCooldownActive } from '../../components/MessageComposer/hooks/useI
 import { EmojiPickerPanel } from './components';
 import { useFrequentlyUsedEmoji } from './hooks/useFrequentlyUsedEmoji';
 import { useSkinTone } from './hooks/useSkinTone';
-import {
-  type EmojiPickerPassthroughProps,
-  resolveEmojiPickerOptions,
-  warnUnsupportedPickerProps,
-} from './options';
 
 const isShadowRoot = (node: Node): node is ShadowRoot => !!(node as ShadowRoot).host;
 
-export type {
-  EmojiPickerNavPosition,
-  EmojiPickerPassthroughProps,
-  EmojiPickerPreviewPosition,
-  EmojiPickerSearchPosition,
-  EmojiPickerSkinTonePosition,
-} from './options';
-
 export type StreamEmojiPickerProps = {
   ButtonIconComponent?: React.ComponentType;
   buttonClassName?: string;
   pickerContainerClassName?: string;
   wrapperClassName?: string;
   closeOnEmojiSelect?: boolean;
-  /**
-   * Presentation + curated layout/behavior options for the picker panel, using
-   * emoji-mart-compatible names (`theme`, `style`, `perLine`, `navPosition`,
-   * `previewPosition`, `searchPosition`, `skinTonePosition`, `categories`,
-   * `exceptEmojis`, `emojiVersion`, `maxFrequentRows`, `noCountryFlags`,
-   * `previewEmoji`, `noResultsEmoji`, `autoFocus`, `onClickOutside`).
-   *
-   * Not every emoji-mart `Picker` option is supported: image sets (`set`,
-   * `getSpritesheetURL`), `custom` emoji, `data`, `i18n`/`locale`, `dynamicWidth`,
-   * `icons`, and `categoryIcons` are rejected by the type and ignored (with a console
-   * warning) at runtime; sizing knobs (`emojiSize`, …) are CSS tokens instead. See the
-   * emoji migration notes in `AI.md`.
-   */
-  pickerProps?: EmojiPickerPassthroughProps;
-  /**
-   * Floating UI placement (default: 'top-end') for the picker popover
-   */
+  /** Floating UI placement (default: 'top-end') for the picker popover. */
   placement?: PopperLikePlacement;
+  /** Focus the search input when the picker opens (default `true`). */
+  autoFocus?: boolean;
+  /** Category ids to show, in order. Defaults to the dataset order. `frequent` always prepends. */
+  categories?: string[];
+  /** Emoji ids to exclude from the grid and search. */
+  exceptEmojis?: string[];
+  /** Called when a pointer press lands outside the open picker. */
+  onClickOutside?: () => void;
+  /** Inline styles applied to the picker panel root. */
+  style?: CSSProperties;
+  /** Color theme. 'auto' (default) inherits the ancestor SDK theme; 'light'/'dark' force it. */
+  theme?: 'auto' | 'light' | 'dark';
   /** Uncontrolled initial skin tone index (0 = default, 1–5 = light → dark). */
   defaultSkinTone?: number;
   /**
@@ -114,19 +97,10 @@ export const StreamEmojiPicker = (props: StreamEmojiPickerProps) => {
   const { pickerContainerClassName, wrapperClassName } = classNames;
 
   const { ButtonIconComponent = IconEmoji } = props;
-  const pickerStyle = props.pickerProps?.style;
-  const options = resolveEmojiPickerOptions(props.pickerProps);
   // Latest-ref so the click-outside listener isn't re-attached when the callback identity
   // changes between renders.
-  const onClickOutsideRef = useRef(props.pickerProps?.onClickOutside);
-  onClickOutsideRef.current = props.pickerProps?.onClickOutside;
-
-  const pickerPropsKeys = Object.keys(props.pickerProps ?? {});
-  useEffect(() => {
-    warnUnsupportedPickerProps(props.pickerProps);
-    // Re-check only when the set of provided keys changes.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [pickerPropsKeys.join(',')]);
+  const onClickOutsideRef = useRef(props.onClickOutside);
+  onClickOutsideRef.current = props.onClickOutside;
 
   useEffect(() => {
     if (!popperElement || !referenceElement) return;
@@ -160,6 +134,9 @@ export const StreamEmojiPicker = (props: StreamEmojiPickerProps) => {
           style={{ left: x ?? 0, position: strategy, top: y ?? 0 }}
         >
           <EmojiPickerPanel
+            autoFocus={props.autoFocus}
+            categories={props.categories}
+            exceptEmojis={props.exceptEmojis}
             frequentlyUsedIds={frequentlyUsedIds}
             onClose={() => {
               setDisplayPicker(false);
@@ -177,10 +154,9 @@ export const StreamEmojiPicker = (props: StreamEmojiPickerProps) => {
               }
             }}
             onSkinToneChange={setSkinTone}
-            options={options}
             skinToneIndex={skinTone}
-            style={pickerStyle}
-            theme={props.pickerProps?.theme}
+            style={props.style}
+            theme={props.theme}
           />
         </div>
       )}

src/plugins/Emojis/__tests__/StreamEmojiPicker.test.tsx

@@ -132,40 +132,10 @@ describe('StreamEmojiPicker session state', () => {
   });
 });
 
-describe('StreamEmojiPicker pickerProps', () => {
-  it('warns about unsupported (emoji-mart) pickerProps, but not about theme/style', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-    const { unmount } = render(
-      <StreamEmojiPicker
-        // @ts-expect-error emoji-mart-only Picker options (image sets) are not supported
-        pickerProps={{ set: 'apple', theme: 'dark' }}
-      />,
-    );
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('set'));
-    unmount();
-
-    warn.mockClear();
-    render(<StreamEmojiPicker pickerProps={{ style: { width: 320 }, theme: 'light' }} />);
-    expect(warn).not.toHaveBeenCalled();
-
-    warn.mockRestore();
-  });
-
-  it('does not warn when only supported (curated) picker options are passed', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    render(
-      <StreamEmojiPicker
-        pickerProps={{ navPosition: 'bottom', perLine: 8, theme: 'light' }}
-      />,
-    );
-    expect(warn).not.toHaveBeenCalled();
-    warn.mockRestore();
-  });
-
+describe('StreamEmojiPicker props', () => {
   it('calls onClickOutside when a pointer press lands outside the open picker', () => {
     const onClickOutside = vi.fn();
-    render(<StreamEmojiPicker pickerProps={{ onClickOutside }} />);
+    render(<StreamEmojiPicker onClickOutside={onClickOutside} />);
     openPicker();
     fireEvent.pointerDown(document.body);
     expect(onClickOutside).toHaveBeenCalledTimes(1);