# emoji-picker-react — complete documentation

> Emoji picker for React: batteries included with `<EmojiPicker />`, or BYOD (bring your own design, design language and design library) with `unstyled` and `emoji-picker-react/primitives`. Both paths share search, keyboard navigation, localization and virtualization. Use your existing Tailwind, shadcn/ui, CSS Modules, Emotion, styled-components, MUI or plain CSS design.

> Generated by `npm run docs:llms`. Do not edit by hand.

Key facts:

- Install: `npm install emoji-picker-react`. Minimal use: `import EmojiPicker from 'emoji-picker-react'; <EmojiPicker onEmojiClick={(e) => insert(e.emoji)} />`.
- Choose batteries included or BYOD for both "I just need an emoji picker" (the default component needs no styling) and "it must match our design system" (`unstyled` or primitives + the project's styling solution).
- Entry points: `emoji-picker-react` (the default picker, enums and types; registers the English dataset), `emoji-picker-react/primitives` (composable parts, hooks, tokens and the same enums; loads the dataset on demand), `emoji-picker-react/data` (search and lookup without React), `emoji-picker-react/data/emojis-<locale>` (28 datasets). The complete export list is below.
- Styling: `--epr-*` CSS variables (they always yield to consumer CSS), `[data-epr-part="…"]` selectors, `className`/`style`. Ordinary resets are handled by library classes; more specific rules and !important can still override structural geometry. With Tailwind v4 or other @layer setups pass `cssLayer="epr"` and declare `@layer epr, theme, base, components, utilities;` first.
- Use `colorScheme="light" | "dark" | "auto"` on Root, or prefer it over `theme` on EmojiPicker (CSS-in-JS wrappers reserve `theme`). Props accept string literals or enums.
- Accessibility: automated axe and keyboard/focus regression checks; grid semantics (emoji buttons are `role="gridcell"`); every UI string localizable through `labels`. Manual screen-reader verification has a separate release protocol.
- Works with React 16.8–19, SSR, React Server Components (client entries are marked "use client"), TypeScript.
- Composition owns presence and placement: Root renders exactly the parts you supply — omit Search, Preview, SkinTone, Panel or Reactions to omit that UI, and place SkinTone inside Search or Preview (or anywhere in Root). The default picker assembles the same parts from its legacy props. Use SearchInput as={Input} with an input-forwarding adapter. Root/EmojiPicker components replace Emoji, CategoryHeader, CategoryButton, SkinToneButton, ClearButton and ExpandButton; List components override grid slots. Use useSearchActions, useCategoryNavigation and usePickerMode for custom controls. Bare Root and unstyled remove all branded decoration; geometry and presence belong to your JSX. Do not invent asChild, onEmojiSelect or a renderer-independent UI engine.
- Read the installed package llms-full.txt first; it matches the installed version. The primitives entry, `unstyled`, `columns`, `components`, `labels` and loader `emojiData` exist from 5.0.0; a 4.x installation has only the v4 props.
- Do not override structural layout (viewport overflow, grid geometry); position the picker by wrapping it.

Exports (generated from the entry sources):

- `emoji-picker-react`: default `EmojiPicker`; values `Categories`, `Emoji`, `emojiByUnified`, `EmojiStyle`, `SkinTonePickerLocation`, `SkinTones`, `SuggestionMode`, `Theme`; types `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`.
- `emoji-picker-react/primitives`: values `Categories`, `CategoryNav`, `darkPickerTokens`, `defaultPickerTokens`, `EmojiStyle`, `Empty`, `lightPickerTokens`, `List`, `LoadError`, `Loading`, `Panel`, `Preview`, `Reactions`, `Root`, `Search`, `SearchInput`, `SkinTone`, `SkinTonePickerLocation`, `SkinTones`, `structuralPickerTokens`, `SuggestionMode`, `Theme`, `useActiveEmoji`, `useCategoryNavigation`, `useEmojiDataState`, `usePickerMode`, `useSearchActions`, `useSearchState`, `useSkinTone`, `Viewport`; types `CategoryButtonRenderProps`, `CategoryConfig`, `CategoryHeaderRenderProps`, `CategoryIcons`, `CategoryNavProps`, `CustomEmoji`, `EmojiClickData`, `EmojiClickHandler`, `EmojiData`, `EmojiDataInput`, `EmojiDataLoader`, `EmojiDataLoaderOptions`, `EmojiDataState`, `EmojiRenderProps`, `EmojiStyleValue`, `EmptyProps`, `ListComponents`, `ListEmoji`, `ListProps`, `LoadErrorProps`, `LoadingProps`, `OnEmojiClickApi`, `PanelProps`, `PickerAppearanceProps`, `PickerComponents`, `PickerCompositionProps`, `PickerLabels`, `PreviewConfig`, `PreviewProps`, `ReactionsProps`, `RootBehaviorProps`, `RootProps`, `SearchInputComponent`, `SearchInputElement`, `SearchInputProps`, `SearchProps`, `SearchState`, `SkinToneButtonRenderProps`, `SkinToneChangeHandler`, `SkinToneProps`, `SkinTonesValue`, `SuggestionModeValue`, `ThemeValue`, `ViewportProps`.
- `emoji-picker-react/data`: values `getEmojiByUnified`, `searchEmojis`; types `EmojiData`, `EmojiDataOptions`, `EmojiInfo`.
- `emoji-picker-react/data/emojis-<locale>`: default export, an `EmojiData` dataset (bn, da, de, en, en-gb, es, es-mx, et, fi, fr, hi, hu, it, ja, ko, lt, ms, nb, nl, pl, pt, ru, sv, th, uk, vi, zh, zh-hant).

Quick reference:

```tsx
// Batteries included: theme the built-in look with colorScheme and --epr-* variables.
import EmojiPicker from 'emoji-picker-react';
<EmojiPicker colorScheme="auto" columns={8} className="my-picker" onEmojiClick={(e) => insert(e.emoji)} />

// Unstyled: same layout and behavior, your CSS on [data-epr-part] selectors (color variables do nothing here).
<EmojiPicker unstyled className="my-picker" />

// Composed: your layout, your components; Root keeps state, keyboard, ARIA and virtualization.
import * as Picker from 'emoji-picker-react/primitives';
<Picker.Root columns={8} style={{ height: 400 }} components={{ Emoji: MyCell }} onEmojiClick={(e) => insert(e.emoji)}>
  <Picker.SearchInput as={MyInput} />
  <Picker.CategoryNav />
  <Picker.Viewport><Picker.List /><Picker.Empty /><Picker.Loading /><Picker.LoadError /></Picker.Viewport>
  <Picker.Preview />
</Picker.Root>

// Data only (no React): search and lookup.
import { searchEmojis, getEmojiByUnified } from 'emoji-picker-react/data';
searchEmojis('party'); getEmojiByUnified('1f389'); // { emoji: '🎉', name: 'party popper', unified, names, … }
```

Contents:

1. Agent integration guide (docs/v5/AGENT_GUIDE.md): installed-version discovery, batteries included/BYOD, typed input/cell contracts, localization and verification
2. Copyable integration prompts (docs/v5/PROMPTS.md): setup, brand styling, design-library composition, recipe adoption and v4-to-v5 migration
3. README (README.md): overview, quick start, choosing a path, styling with any solution, common tasks
4. Props reference (PROPS.md): every prop of the default <EmojiPicker />
5. CSS variables (CSS_VARIABLES.md): every --epr-* design token
6. Customization (CUSTOMIZATION.md): custom emojis and groups, category icons, preview, CSP nonce
7. Internationalization (INTERNATIONALIZATION.md): locale datasets and labels
8. Adoption (docs/v5/ADOPTION.md): native input, loading recovery, registry installation and source downloads
9. v5 API (docs/v5/API.md): all v5 additions with examples
10. Primitives (docs/v5/PRIMITIVES.md): composable parts, hooks, custom cells, grammar
11. Styling (docs/v5/STYLING.md): tokens, parts, cascade, structural rules
12. Styling recipes by library (docs/v5/STYLING_RECIPES.md): theme, unstyled and composed snippets for plain CSS, CSS Modules, Tailwind, shadcn/ui, Emotion, styled-components and MUI
13. Data API (docs/v5/DATA_API.md): framework-free search and lookup
14. Migrating from v4 (docs/v5/MIGRATION.md): what changed and how to upgrade
15. Website examples (website/README.md): typed customization, locale loading and composition
16. Design recipes (stories/recipes/README.md): 25 designs, each in seven styling stacks
17. Styling integrations (stories/integrations/README.md): shadcn/ui, Tailwind, Emotion, styled-components, CSS Modules, CSS, MUI
18. Example app (example/README.md): Vite + React 19 app running the batteries-included, unstyled, composed and data-API paths
19. Worked example: team chat picker composition (stories/recipes/team-chat/picker.tsx; picker only, demo app chrome excluded)

<!-- source: docs/v5/AGENT_GUIDE.md -->

<!-- Agent integration guide -->

# Integrating emoji-picker-react: agent guide

A decision-first guide for coding agents and the people reviewing their output. Every snippet here matches the shipped API.

For a task to paste into a coding agent, use the [setup, customization, recipe
adoption and v5 migration prompts](PROMPTS.md). Each is self-contained and
starts with installed-version discovery; the contracts below remain authoritative.

## 1. Check the installed version first

Everything below exists from `emoji-picker-react@5.0.0`. A 4.x installation has the same default `<EmojiPicker />` but none of the v5 additions.

1. Read the app's `package.json`, lockfile, and `node_modules/emoji-picker-react/package.json` (`version`, `exports`).
2. Read `node_modules/emoji-picker-react/llms-full.txt`: the full reference for that exact version, usable offline. `llms.txt` is a short index.
3. If the installed version is 4.x, use only v4 APIs (no `/primitives`, `unstyled`, `columns`, `components`, `labels` or loader `emojiData`), or upgrade: [MIGRATION.md](MIGRATION.md) lists every behavior change.

## 2. Pick a path

| The app needs | Use | The app styles | The picker owns |
| --- | --- | --- | --- |
| An emoji picker, fast | `<EmojiPicker />` | Nothing | Complete UI and behavior |
| The built-in look in brand colors | `<EmojiPicker />` + `colorScheme` + `--epr-*` color variables | Variables | Complete UI and behavior |
| Its own design, supplied layout | `<EmojiPicker unstyled />` | Every part, via `[data-epr-part]` | Layout, geometry, behavior |
| Its own layout or design-library components | `emoji-picker-react/primitives` | Layout and parts | State, grid, keyboard, ARIA, virtualization |
| Search or lookup without UI | `emoji-picker-react/data` | Everything | Dataset search and lookup |

BYOD means **bring your own design, design language and design library**. It works with plain CSS, CSS Modules, Tailwind, shadcn/ui, Emotion, styled-components and MUI.

**The styling rule.** Color variables (`--epr-bg-color`, `--epr-highlight-color`, …) theme the *built-in look*. `unstyled` and a bare `Root` remove the built-in look, so color variables do nothing there. Size variables (`--epr-emoji-size`, paddings, heights) work in every mode. To reuse the built-in look in a composition, pass `appearance="default"` to `Root`.

## 3. Batteries included

```tsx
import EmojiPicker from 'emoji-picker-react';

<EmojiPicker
  colorScheme="auto"
  columns={8}
  onEmojiClick={(data) => insertAtCaret(data.emoji)}
/>
```

`insertAtCaret` is your application's function. The host owns insertion, trigger state, placement and popover/dialog dismissal. Preserve the text selection and any suffix when inserting. For custom image emojis, `data.emoji` is the custom id; map it to your token or attachment. Search and selection never send messages.

## 4. BYOD with design-library components

```tsx
import * as React from 'react';
import * as Picker from 'emoji-picker-react/primitives';
import { Input, Button } from './design-system';

function Cell({ emoji, ...managed }: Picker.EmojiRenderProps) {
  return (
    <Button {...managed} variant={emoji.isActive ? 'highlighted' : 'quiet'} />
  );
}

const components = { Emoji: Cell };
const loadFrench = () => import('emoji-picker-react/data/emojis-fr');

function ComposerPicker({ onSelect }: {
  onSelect: (data: Picker.EmojiClickData) => void;
}) {
  return (
    <Picker.Root
      emojiData={loadFrench}
      onEmojiClick={onSelect}
      components={components}
      columns={8}
      className="composer-picker"
      style={{ height: 400 }}
      labels={{
        searchLabel: 'Rechercher un emoji',
        searchPlaceholder: 'Rechercher',
        loading: 'Chargement…',
        loadingError: 'Chargement impossible.',
        retryLoading: 'Réessayer',
      }}
    >
      <Picker.Panel className="composer-picker-panel">
        <Picker.SearchInput as={Input} />
        <Picker.Viewport>
          <Picker.List />
          <Picker.Empty />
          <Picker.Loading />
          <Picker.LoadError />
        </Picker.Viewport>
      </Picker.Panel>
    </Picker.Root>
  );
}
```

Adapt `Input` and `Button` props to the installed design library.

**Inputs.** `SearchInput as={Input}` infers `Input`'s own props, including required ones. `Input` must forward the supplied props and ref to a native `<input>`. Root owns the value: use `searchValue` / `onSearchChange` on Root, never `value`, `defaultValue` or a second controller on SearchInput. Libraries whose ref lands on a wrapper (MUI `TextField`) need an adapter: `inputRef` for the ref, `slotProps.htmlInput` for native props. See the copyable adapter in [ADOPTION.md](ADOPTION.md#inputs-with-a-wrapper-ref-including-mui).

**Cells, headers and controls.** `components` on Root or EmojiPicker replaces `Emoji`, `CategoryHeader`, `CategoryButton`, `SkinToneButton`, `ClearButton` and `ExpandButton`. Each receives managed props plus metadata: `emoji` (with `isActive`), `category` (with `isActive` on buttons) or `tone`. Remove the metadata and spread **all** remaining props, including `className` and the inline position `style`, onto one native element. Keep component identities stable (define them at module scope). Add a visible focus style. Design-library buttons often need `minWidth: 0` and compatible padding to fit the managed cell.

**Custom UI from hooks** (inside Root): `useActiveEmoji()` for previews, `useSkinTone()` for tone menus (respects controlled `skinTone`), `useSearchState()` (read-only) and `useSearchActions()` (`setValue`, `clear`) for search UI, `useCategoryNavigation()` (`categories`, `activeCategory`, `jumpToCategory`) for tabs, `usePickerMode()` (`reactionsOpen`, `expand`, `collapse`) for reactions, `useEmojiDataState()` (`loading`, `error`, `retry`) for loading UI.

## 5. Composition grammar

- One `Root` per picker. One `Viewport` containing one `List`. Wrappers, memo and HOCs around parts are fine.
- `Search` (input + icon + clear button) and `SearchInput` (only the input, or yours) are alternatives: use one.
- Optional parts: `CategoryNav` (`orientation="vertical"` for rails), `Preview`, `SkinTone`, `Empty`, `Loading`, `LoadError`. Search and Preview never insert SkinTone automatically; place it directly where needed.
- Root renders exactly the supplied children. For compact reactions, place `Reactions` outside `Panel` and put expanded parts inside `Panel`. Put layout props directly on Panel; there is no composition switch or panelProps prop.
- Conditionally mount Root to control its lifetime; unmounting aborts pending loading and discards picker state. The assembled EmojiPicker keeps its legacy `open` prop, which, as in v4, keeps search, skin tone and reactions mode while closed.
- Portaling a whole Root (into a popover) works; portaling individual parts out of Root does not.

## 6. Mistakes to avoid

| Don't | Do |
| --- | --- |
| `unstyled` + `--epr-bg-color` and expect a themed picker | Theme the default picker with variables, or style `[data-epr-part]` selectors under `unstyled` |
| Bare `Root colorScheme="dark"` and expect dark controls | `Root appearance="default" colorScheme="dark"` |
| `import { Categories } from 'emoji-picker-react'` in a primitives app | Import enums from `emoji-picker-react/primitives`; the main entry bundles the English dataset |
| Invent `asChild`, `onEmojiSelect`, `render` props, children inside `List`, or setters on `useSearchState` | Use `components`, `onEmojiClick`, and the action hooks above |
| `value` / `onChange` on `SearchInput` to control search | `searchValue` / `onSearchChange` on Root |
| Drop `style` or `className` from a custom cell | Spread every managed prop onto the native button |
| `stopPropagation` to block selection | `onEmojiClick` is the selection callback; filter there |
| Query cells with `getByRole('button')` in tests | `getByRole('gridcell', { name: 'grinning face' })` |
| A bare `Root` with no height | Give Root a height (`style={{ height: 400 }}` or a class); otherwise every emoji renders at once and development builds warn |
| A new loader function on every render | Hoist the loader to module scope; a new identity means a new dataset |
| Hide the default focus ring on custom controls without a replacement | Provide `:focus-visible` styles |

## 6a. Types

Import types from the entry you use: `EmojiClickData`, `EmojiClickHandler`, `PickerLabels`, `CustomEmoji`, `PreviewConfig`, `PickerComponents`, `EmojiRenderProps`, `EmojiDataLoader` and the literal unions (`ThemeValue`, `EmojiStyleValue`, `SkinTonesValue`, `SuggestionModeValue`) come from both `emoji-picker-react` and `emoji-picker-react/primitives`; `RootProps` and the part prop types from `/primitives`; `EmojiInfo` from `/data`. The export index in `llms.txt` is generated from the entry sources and is complete.

## 7. Data, loading and bundle size

Hoist an emoji loader at module scope or memoize it. Loaders receive `{ signal }`; pass it to `fetch`. Rejection and malformed payloads show `LoadError` and set `useEmojiDataState().error`; `retry()` starts another attempt. Source changes, closing and unmount abort old attempts.

The main entry and `/data` register the English dataset synchronously. A composed app that wants the dataset deferred must import runtime values only from `/primitives`. A static locale import is synchronous and SSR-safe; a dynamic loader defers the dataset. The initial JavaScript budget excludes deferred dataset traffic and React.

## 8. Styling details

Per-library snippets (plain CSS, CSS Modules, Tailwind, shadcn/ui, Emotion, styled-components, MUI) for the theme, unstyled and composed paths: [STYLING_RECIPES.md](STYLING_RECIPES.md).

- Target parts with `[data-epr-part]`: `root`, `panel`, `search`, `search-input`, `search-clear`, `skin-tone`, `skin-tone-button`, `category-nav`, `category-tab`, `viewport`, `list`, `category`, `category-label`, `category-content`, `emoji`, `variation-picker`, `preview`, `empty`, `loading`, `load-error`, `reactions`, `reaction`, `expand-reactions`. State: `[data-epr-active]` (hovered or focused emoji, active tab or tone), `aria-selected`, `aria-pressed`.
- Variables yield to any consumer selector (zero specificity). For Tailwind v4, declare `@layer epr, theme, base, components, utilities;` and pass `cssLayer="epr"`.
- Under `unstyled` or a bare Root, give `[data-epr-part='variation-picker']` and sticky `category-label`s a background; they are transparent overlays otherwise.
- Do not override Viewport overflow, cell dimensions, category positioning or the inline cell positions. Change size variables or `columns` instead.
- Root dimensions come from `style`/`className`; EmojiPicker also takes `width` and `height`. With `columns`, the width fits the columns unless set.
- Use `colorScheme`, not `theme`, on components wrapped by Emotion, styled-components or MUI `styled()`.
- `dir="rtl"` mirrors the grid, tabs and tone fan; arrow keys follow the visual direction. Custom cells receive their position as `top` and `insetInlineStart`; spread `style` rather than reading `left`.
- `prefers-reduced-motion: reduce` turns off the library's own transitions.

## 9. Localization and accessibility

Locale datasets translate emoji names and category names. `labels` translates controls and announcements; `previewConfig.defaultCaption` sets the preview caption. Complete localization covers every visible and announced string in your composition: see [INTERNATIONALIZATION.md](../../INTERNATIONALIZATION.md).

Keep the managed ARIA props. Test keyboard selection, search and IME input, focus restoration and nested Escape inside the real host popover or dialog: Escape closes an open variation or tone menu before reaching the host. Custom emojis with duplicate names share an accessible name; scope test queries to a category.

<!-- source: docs/v5/PROMPTS.md -->

<!-- Copyable integration prompts -->

# Copyable setup, customization and migration prompts

Copy a block into your coding agent. Replace the bracketed fields where present;
leave them blank to use your application's existing conventions. Attach a
screenshot or selected recipe's implementation files when asking for a design.
Each prompt includes version discovery so it also works in an existing project.

The prompts target emoji-picker-react 5. A 4.x installation does not provide
primitives, `unstyled`, `columns`, `components`, `labels` or loader
`emojiData`, so each prompt checks the installed version first. The installed
package's `llms-full.txt` describes that exact version.

## Quick setup

Use this when you want a working picker with its built-in appearance.

```text
Integrate emoji-picker-react into this application's emoji entry flow.

Inspect package.json, the lockfile, the resolved package version and exports,
and the installed llms-full.txt. Use the existing package manager and
framework conventions. If the installed version is below 5, upgrade to
emoji-picker-react@5 (or explain why you cannot) before using v5 APIs.

Start with the default EmojiPicker component. It needs no stylesheet import
or primitives. Prefer colorScheme="auto" for v5. Connect onEmojiClick's data
payload to the existing application state. For a text composer, insert
data.emoji at the saved selection, preserving surrounding text and restoring
the caret. Map custom emoji IDs to the application's representation.

The application owns the trigger, popover/dialog, placement and dismissal.
Preserve focus restoration and let picker menus handle Escape before closing
the host. In an RSC application, keep interactive UI in a client component;
use only emoji-picker-react/data for server-side search or lookup.

Deliver the changed files and exact setup commands. Run the application's
existing type/build checks and verify selection, search, keyboard navigation,
dismissal and focus restoration. Report any checks you could not run.
```

## Match my brand

Use this for colors, typography, radii and spacing while retaining the built-in
picker layout. Describe your visual requirements or attach a screenshot.

```text
Customize this application's emoji-picker-react to match:
[brand colors, typography, light/dark requirements, or attached screenshot]

Inspect the installed version, exports and matching llms-full.txt before
choosing APIs; v5 features need emoji-picker-react 5 or later. Preserve the
existing integration, callbacks and state ownership.

Keep the default EmojiPicker and theme its built-in appearance using a scoped
className and documented --epr-* variables. Use this application's existing
styling solution and prefer colorScheme over theme. Keep light and dark text,
backgrounds and focus indicators readable. For Tailwind v4, declare the epr
layer before the application's layers and pass cssLayer="epr".

Use documented size tokens or columns for sizing; preserve viewport overflow,
virtualized cell positions and category geometry. Avoid hashed internal class
names. If changing composition or markup is actually necessary, explain that
choice and use the supported primitives/components contracts.

Deliver the component and styling files, show where each is imported, and
explain how to adjust the colors and dimensions. Check both color schemes,
small containers, keyboard focus and the application's type/build checks.
```

## Build with my design library

Use this when you want your own layout or controls. The styling library field
can name CSS Modules, Tailwind, shadcn/ui, Emotion, styled-components, MUI,
ShipStyles or StyleX. Use the library already configured in the application;
its own version and build setup determine the available styling APIs.

```text
Build an emoji picker matching [design or attached screenshot] using
[styling/design library already used by this application].

Inspect the installed emoji-picker-react version, exports and llms-full.txt,
and the styling library's installed version and existing configuration. Use
documented v5 APIs and real library APIs. Include any necessary setup changes.

Choose the smallest supported approach: theme EmojiPicker for its existing
look, use EmojiPicker unstyled for its supplied layout with my appearance, or
use emoji-picker-react/primitives when I need my own composition or controls.
Color tokens theme the built-in appearance; bare Root and unstyled need part
styles. Root appearance="default" intentionally reuses built-in leaf styling.

For primitives, JSX determines presence and placement. Root renders only its
children. Omit unwanted parts; put SkinTone where it belongs. For compact
reactions, compose Reactions outside Panel and expanded content inside Panel.
Do not add composition, panelProps or legacy visibility switches to Root.
Use SearchInput as with a ref-forwarding input adapter when appropriate.
Keep component identities stable and preserve managed refs, handlers, style,
ARIA and data-epr-* props on the required underlying elements. Preserve
viewport overflow, cell geometry, virtualization and keyboard navigation.

Connect selection, controlled state and host dismissal to the application.
Deliver complete files, dependencies and setup, with checks for search,
selection, focus, Escape, responsive layout and the existing type/build gates.
```

## Adapt a recipe

Attach the selected recipe's source files and specify its styling variant.
The current catalog supplies CSS, CSS Modules, Emotion, styled-components,
MUI, Tailwind and shadcn/ui variants. A variant for another library needs a
real implementation and verification before being described as available.

```text
Adapt the attached emoji-picker-react recipe into this application:
Recipe: [name]
Styling variant: [library]
Integration target: [composer, comment field, status dialog, or other surface]

Read the attached source and inspect the application's installed versions,
package exports and matching llms-full.txt. Keep the recipe's actual picker
composition, interaction behavior and styling in the selected library. Use
documented v5 APIs. If the supplied files do not include the requested variant,
identify that gap and implement it using the installed styling library's APIs.

Replace mock application chrome and state with our real components and data.
Preserve insertion at the saved selection, custom emoji mapping, controlled
state ownership, dismissal and focus restoration. Do not send a message when
an emoji is selected. Preserve library-owned navigation, ARIA, virtualization,
managed props and refs. Primitive presence belongs to JSX.

Deliver all required component, styling and setup files, with exact import
paths and dependencies. Explain the integration points and customization
options. Run the application's existing checks and verify the recipe's
interactive states and light/dark/responsive requirements. Report limitations.
```

## Audit a v4-to-v5 migration

Use this for a review and migration plan before changing application code.

```text
Audit this application's migration from emoji-picker-react v4 to v5.
Produce a file-specific plan before making implementation changes.

Inventory picker imports, resolved versions, props, callbacks, controlled
state, locale datasets, custom emojis, CSS selectors and interaction tests.
Read documentation matching the v5 target version, its package
llms-full.txt, and its migration/API compatibility contract.

Separate required compatibility work from optional adoption of new features.
Keep the default EmojiPicker where it already meets our needs. Existing enums,
theme and useful default-picker visibility props remain supported; primitives
are optional. Prefer colorScheme in new CSS-in-JS integrations.

Call out the native emoji default and platform support filtering; an explicit
emojiStyle="apple" preserves image rendering where required. Audit supported
package subpaths and deprecated locale aliases, changed managed markup/grid
roles, zero-specificity tokens and cascade layers, responsive column spacing,
prop updates after mount, widened enum/literal types, and SSR/client boundaries.
Preserve callback payloads, search/skin-tone ownership and custom emoji IDs.

Return required changes by file, optional improvements separately, behavior
choices needing a product decision, and a verification plan covering types,
search/IME, selection, focus, Escape, localization, themes and representative
platforms. Review intentional visual changes before updating image baselines.
```

## Apply a v4-to-v5 migration

Use this after choosing a target and reviewing the audit. State whether you
want to keep the previous image appearance or adopt native emoji rendering.

```text
Migrate this application to emoji-picker-react v5:
[target version, e.g. latest 5.x]
Appearance policy: [retain Apple images / adopt native emoji rendering]
Approved audit or requirements: [attach or describe]

Inspect the current code, resolved versions and target-version documentation,
including its migration/API compatibility contract and llms-full.txt. Use the
project's package manager and update its lockfile consistently. If the target
cannot be resolved, report that before changing code to depend on it.

Make the required compatibility changes while preserving working callbacks,
custom emojis, locale behavior, host integration and controlled state. Keep
existing supported APIs and use the default picker unless our layout requires
primitives. Preserve Apple rendering with explicit emojiStyle="apple" when
requested; explain native platform filtering if adopting the native default.
Use canonical documented package entries and stable data-epr-part selectors.
Prefer colorScheme when touching styling-library wrappers. If using primitives,
compose presence through JSX and keep Reactions outside the expanded Panel.

Update affected tests to assert public behavior and managed grid semantics:
emoji grid cells use role=gridcell and categories use named rowgroups. Retain
keyboard, search/IME, skin tone, custom emoji, focus-restoration, nested-Escape,
locale and responsive coverage. Check the actual host popover/dialog and SSR
path. Review visual differences individually; do not bulk-replace baselines.

Deliver the changes, setup commands, compatibility decisions and verification
results. List remaining manual or platform checks and any unresolved blockers.
```

## API references

These prompts guide integration; the API contracts remain authoritative:
[default picker props](../../PROPS.md), [v5 API](API.md),
[primitives](PRIMITIVES.md), [customization](../../CUSTOMIZATION.md),
[localization](../../INTERNATIONALIZATION.md) and [data API](DATA_API.md).

<!-- source: README.md -->

<!-- README -->

# Emoji Picker React

**Batteries included. Or BYOD — bring your own design.**

One emoji-picker engine, with two ways to build your UI: use the complete picker, or bring your own design, design language and design library.

> **Batteries included:** `npm install emoji-picker-react`, render `<EmojiPicker />`, done — a complete, accessible, themed picker with search, categories, skin tones, recents and keyboard navigation. No CSS import, no configuration, no design work.
>
> **BYOD (bring your own design):** pass `unstyled`, or compose your own layout from `emoji-picker-react/primitives`, and style it with whatever your app already uses — Tailwind, shadcn/ui, CSS Modules, Emotion, styled-components, MUI or plain CSS. Accessibility, keyboard navigation and virtualization stay built in.

[![npm downloads](https://img.shields.io/npm/dm/emoji-picker-react.svg)](https://www.npmjs.com/package/emoji-picker-react)

**[Live demo](https://ealush.com/emoji-picker-react)** · **[Props](PROPS.md)** · **[BYOD](#byod-bring-your-own-design)** · **[Common tasks](#common-tasks)** · **[For AI assistants](#for-ai-assistants)** · **[Report a bug](https://github.com/ealush/emoji-picker-react/issues)** · **[Sponsor](https://github.com/sponsors/ealush)**

![image](https://github.com/ealush/emoji-picker-react/assets/11255103/48901306-e7fd-49cd-8f1e-9b214083a61d)

![reactions](https://github.com/ealush/emoji-picker-react/assets/11255103/c28cc954-dc1d-4d82-91a8-64a74cf1d598)

## Features

- **Batteries included** — one component, sensible defaults, light/dark/auto themes, no stylesheet to import.
- **BYOD** — `unstyled` drops the chrome and composable primitives let you build any layout, styled with plain CSS, CSS Modules, Tailwind, shadcn/ui, Emotion, styled-components or MUI. See [25 designs](#design-examples) built this way.
- **Accessible** — full keyboard navigation, ARIA grid semantics, localizable labels, right-to-left layouts, reduced-motion support and automated axe checks.
- **Reactions mode** — a compact reactions bar that expands to the full picker.
- **Localized** — 28 emoji datasets; translate search, categories, previews, reactions, skin tones, loading errors and retry controls, including accessible announcements.
- **Emoji styles** — native (default), Apple, Google, Facebook, Twitter; native mode filters detected unsupported OS glyphs, including individual sequences and skin tones. See [detection limits](docs/v5/API.md#5c-native-emoji-support-detection).
- **Custom emojis** — image-based emojis, optionally in their own named groups.
- **Lean when you want** — the primitives entry loads the dataset on demand (a 34 KiB min+gz startup budget including ShipStyles; see the consumer gate); a framework-free data API for search and lookup.
- **Modern React** — React 16.8 through 19, SSR, React Server Components (`"use client"` entries), TypeScript types included; ships ES2020 for every browser since 2020 and any modern bundler.

> **Upgrading from v4?** Most code works unchanged; the default emoji style is now native, and markup, styling and package boundaries have changed. See [Migrating from v4](docs/v5/MIGRATION.md). The APIs on this page need `emoji-picker-react@5` or later.

## Copyable integration prompts

Use the [setup, customization, recipe adoption and v5 migration prompts](docs/v5/PROMPTS.md)
to give a coding agent a concrete starting point for your application. Each
prompt checks the installed version and keeps integration behavior explicit.

## Quick start (batteries included)

```bash
npm install emoji-picker-react
```

Requires **React 16.8 or later** and **Node 18 or later** in your build toolchain. (Contributors to this repository use Node 24; see [CONTRIBUTING.md](CONTRIBUTING.md).)

```jsx
import EmojiPicker from 'emoji-picker-react';

function App() {
  return (
    <EmojiPicker onEmojiClick={(emojiData) => console.log(emojiData.emoji)} />
  );
}
```

That is the whole setup. `onEmojiClick` receives an `EmojiClickData` object (`emoji`, `unified`, `names`, `imageUrl`, `activeSkinTone`, …) and the event.

```jsx
<EmojiPicker colorScheme="dark" width={320} height={400} previewConfig={{ showPreview: false }} />
```

See [PROPS.md](PROPS.md) for every prop.

## Choose your path

| You want | Use | You style |
| --- | --- | --- |
| A complete picker now | `<EmojiPicker />` | Nothing |
| The built-in look in your brand's colors and sizes | `<EmojiPicker />` + `colorScheme` and `--epr-*` variables | A few variables |
| Your own design on the supplied layout | `<EmojiPicker unstyled />` | Every part, with your CSS or styling library |
| Your own layout and components | `emoji-picker-react/primitives` | Layout and parts, or reuse the built-in look with `appearance="default"` |

Every path keeps the same behavior: keyboard navigation, focus management, ARIA semantics, virtualization, skin tones, variations, recents, search and localization.

**One rule decides how styling works:** color variables (`--epr-bg-color`, `--epr-highlight-color`, …) theme the *built-in look*. `unstyled` and a bare primitives `Root` remove the built-in look, so color variables have no effect there. You style the parts directly. Size variables (`--epr-emoji-size`, paddings, heights) apply in every mode.

## BYOD: bring your own design

Bring your own design, design language and design library. Keep the supplied layout with `unstyled`, or compose the parts and use your own input, emoji buttons, category headers, preview and tone controls. Search, localization, keyboard navigation and virtualization share the same engine in both paths.

The picker needs no stylesheet import. Its CSS is injected automatically, once per document or shadow root, and scoped so it never leaks into your app.

How overrides work, so you never fight specificity:

- **Design variables (`--epr-*`) always yield to your CSS.** Their defaults are emitted at zero specificity, so a single class wins in any load order.
- **Parts are targetable** with stable `[data-epr-part="…"]` selectors: `root`, `panel`, `search`, `search-input`, `search-clear`, `skin-tone`, `skin-tone-button`, `category-nav`, `category-tab`, `viewport`, `list`, `category`, `category-label`, `category-content`, `emoji`, `variation-picker`, `preview`, `empty`, `loading`, `load-error`, `reactions`, `reaction`, `expand-reactions`. State is exposed as `[data-epr-active]` (hovered or focused emoji, active tab or tone), `[aria-selected="true"]` (current tab) and `[aria-pressed="true"]` (current tone). The full contract: [docs/v5/STYLING.md](docs/v5/STYLING.md).
- **CSS ownership is explicit.** Library classes protect layout from ordinary element/universal resets. More specific rules and `!important` can still override geometry; preserve the [structural contract](docs/v5/STYLING.md).
- **Layered frameworks:** with Tailwind v4 (or any `@layer`-based setup), pass `cssLayer="epr"` and declare the layer first — `@layer epr, theme, base, components, utilities;` — so utilities override the picker.

### Theme the built-in look with CSS variables

```css
.my-picker {
  --epr-bg-color: #0f172a;
  --epr-category-label-bg-color: #0f172ae6;
  --epr-search-input-bg-color: #1e293b;
  --epr-search-input-bg-color-active: #1e293b;
  --epr-picker-border-color: #1e293b;
  --epr-text-color: #cbd5e1;
  --epr-highlight-color: #22d3ee;
  --epr-hover-bg-color: #1e293b;
  --epr-focus-bg-color: #334155;
  --epr-emoji-size: 28px;
}

.my-picker [data-epr-part='category-label'] {
  text-transform: uppercase;
  letter-spacing: 0.08em;
}
```

```jsx
<EmojiPicker colorScheme="dark" className="my-picker" />
```

Sticky category labels and the search field have their own surfaces, so set their variables along with `--epr-bg-color`. All variables: [CSS_VARIABLES.md](CSS_VARIABLES.md).

### Unstyled: your design, the supplied layout

`unstyled` removes decorative styling from every part: colors, borders, rounding, button resets, typography and the search icon. Layout, geometry, virtualization, keyboard behavior and visibility stay managed. You start from plain browser controls and style the parts with your own CSS. This is a complete starting point:

```css
.my-picker {
  background: Canvas;
  color: CanvasText;
  border: 1px solid #8884;
  border-radius: 12px;
  font: 14px system-ui, sans-serif;
}
.my-picker [data-epr-part='search-input'] {
  padding-inline-start: 10px;
  border: 1px solid #8886;
  border-radius: 8px;
  background: transparent;
  color: inherit;
  font: inherit;
}
.my-picker :is([data-epr-part='emoji'], [data-epr-part='category-tab'],
    [data-epr-part='search-clear'], [data-epr-part='skin-tone-button']) {
  border: 0;
  border-radius: 8px;
  background: transparent;
  color: inherit;
  cursor: pointer;
}
.my-picker [data-epr-part='emoji'][data-epr-active],
.my-picker [data-epr-part='category-tab'][aria-selected='true'] {
  background: #8882;
}
.my-picker :is(button, input):focus-visible {
  outline: 2px solid Highlight;
  outline-offset: -2px;
}
.my-picker [data-epr-part='category-label'] {
  font-size: 12px;
  font-weight: 600;
  background: Canvas;
}
.my-picker [data-epr-part='variation-picker'] {
  background: Canvas;
  border: 1px solid #8884;
  border-radius: 10px;
  box-shadow: 0 4px 12px #0003;
}
```

```jsx
<EmojiPicker unstyled className="my-picker" />
```

It follows the page's light or dark `color-scheme`. Keep a visible focus style on buttons and the input. Overlays such as the skin-tone variation popover (`variation-picker`) are transparent until you give them a surface. The same selectors work from CSS Modules (`:global([data-epr-part='emoji'])` inside your module class), Emotion, styled-components, Tailwind arbitrary variants (`[&_[data-epr-part=emoji]]:rounded-lg`) and MUI's `styled`.

### Tailwind CSS (v4)

```css
/* app.css */
@layer epr, theme, base, components, utilities;
@import 'tailwindcss';
```

```jsx
<EmojiPicker
  cssLayer="epr"
  className="rounded-2xl shadow-xl [--epr-bg-color:var(--color-white)] [--epr-highlight-color:var(--color-indigo-600)] [--epr-hover-bg-color:var(--color-indigo-50)] [&_[data-epr-part=emoji]]:rounded-lg"
/>
```

Utilities apply to the root; arbitrary properties set variables and arbitrary variants reach the parts. For a fully custom design, add `unstyled` and style the parts with utilities instead of variables.

### shadcn/ui

Map the picker's variables to shadcn's theme variables once; light, dark and custom themes then follow automatically:

```css
.emoji-picker {
  --epr-bg-color: var(--popover);
  --epr-category-label-bg-color: var(--popover);
  --epr-text-color: var(--muted-foreground);
  --epr-highlight-color: var(--primary);
  --epr-hover-bg-color: var(--accent);
  --epr-focus-bg-color: var(--accent);
  --epr-picker-border-color: var(--border);
  --epr-search-input-bg-color: transparent;
  --epr-search-border-color: var(--input);
  --epr-search-border-color-active: var(--ring);
}
```

```jsx
<PopoverContent className="w-auto p-0">
  <EmojiPicker cssLayer="epr" className="emoji-picker" onEmojiClick={(e) => insert(e.emoji)} />
</PopoverContent>
```

For a component that uses your shadcn input and buttons directly, install the [registry component](#ready-to-adapt-starters).

### Emotion, styled-components and MUI

```jsx
import styled from '@emotion/styled'; // or 'styled-components', or '@mui/material/styles'

const ThemedPicker = styled(EmojiPicker)`
  --epr-bg-color: ${(p) => p.theme.colors.surface};
  --epr-category-label-bg-color: ${(p) => p.theme.colors.surface};
  --epr-highlight-color: ${(p) => p.theme.colors.accent};
  border-radius: 16px;
`;

<ThemedPicker colorScheme="dark" />;
```

Use `colorScheme` (not `theme`) with CSS-in-JS wrappers: Emotion, styled-components and MUI reserve a `theme` prop on components they wrap. `theme` still works everywhere else (v4 compatible).

Every technique above has a complete, runnable version in [`stories/integrations`](stories/integrations) and, per design, in [`stories/recipes`](stories/recipes). **[Styling recipes by library](docs/v5/STYLING_RECIPES.md)** collects theme, unstyled and composed snippets for plain CSS, CSS Modules, Tailwind, shadcn/ui, Emotion, styled-components and MUI; the [`example/`](example) app runs all three paths.

## Compose your own layout

`emoji-picker-react/primitives` exposes the picker's parts. Arrange them in your layout and use your design library's components for the input, emoji cells, category headers and controls. Root manages state and navigation; one Viewport owns one List.

```tsx check
import React from 'react';
import * as Picker from 'emoji-picker-react/primitives';

export function EmojiMenu({ insert }: { insert: (emoji: string) => void }) {
  return (
    <Picker.Root
      appearance="default"
      colorScheme="light"
      columns={8}
      style={{ height: 400 }}
      onEmojiClick={(emoji) => insert(emoji.emoji)}
    >
      <Picker.Search />
      <Picker.CategoryNav />
      <Picker.Viewport>
        <Picker.List />
        <Picker.Empty />
        <Picker.Loading />
        <Picker.LoadError />
      </Picker.Viewport>
      <Picker.Preview />
    </Picker.Root>
  );
}
```

`appearance="default"` reuses the built-in look, so `colorScheme` and color variables apply. Leave it out to style every part yourself, exactly like `unstyled`. Root has no default height: set one so the list scrolls and virtualizes.

- **Parts:** `Root`, `Search` (input with icon and clear button), `SearchInput` (just the input, or yours), `CategoryNav` (`orientation="vertical"` for side rails), `Viewport`, `List`, `Preview`, `SkinTone`, `Empty`, `Loading`, `LoadError`; `Panel` and `Reactions` manage expanded and compact reaction content when composed. Presence and placement are owned by JSX; Root has no composition switch.
- **Your components:** `<Picker.SearchInput as={Input} />` accepts your input component's props and forwards its ref to the native input; Root owns its value. `components={{ Emoji, CategoryHeader, CategoryButton, SkinToneButton, ClearButton, ExpandButton }}` on Root or EmojiPicker replaces those elements with yours while the library keeps their behavior and measured geometry. Spread the props you receive onto one native element, and give it a visible focus style.
- **Hooks for custom UI:** `useActiveEmoji()` (custom previews), `useSkinTone()` (custom tone menus), `useSearchState()` / `useSearchActions()` (custom search UI), `useCategoryNavigation()` (custom tabs), `usePickerMode()` (reactions bar ↔ full picker), `useEmojiDataState()` (loading and retry).
- **Size:** `columns` sets the emojis per row and fits the width to them; without it, set a width and the columns follow.
- **Lean:** the primitives entry loads the emoji dataset on demand. Pass `emojiData` (an object, or a loader like `() => import('emoji-picker-react/data/emojis-fr')`) to control it. Import enums such as `Categories` from `emoji-picker-react/primitives`, not the main entry, to keep the dataset out of your initial bundle.

The composition path keeps grid geometry, keyboard behavior and ARIA managed; there is no renderer-independent DOM engine. For search without React or UI, use the [data API](#data-api).

Full reference: [docs/v5/PRIMITIVES.md](docs/v5/PRIMITIVES.md) and [docs/v5/API.md](docs/v5/API.md). A copyable design-library walkthrough (including MUI): [docs/v5/ADOPTION.md](docs/v5/ADOPTION.md).

## Common tasks

**Dark mode** — `<EmojiPicker colorScheme="dark" />` (or `"auto"` to follow the OS).

**Reactions bar (like Slack or iMessage)** — `<EmojiPicker reactionsDefaultOpen reactions={['1f44d', '2764-fe0f', '1f602']} onReactionClick={...} />`. The "+" expands to the full picker; `allowExpandReactions={false}` keeps it compact.

**Insert the emoji into a text field** — use `emojiData.emoji` from `onEmojiClick`:

```jsx
<EmojiPicker onEmojiClick={(emojiData) => setText((text) => text + emojiData.emoji)} />
```

**Open it in a popover or dropdown** — render the picker inside your popover component (Radix, MUI, Headless UI, …); it has no positioning of its own.

**Localize it** — pass a dataset and translated UI strings:

```jsx
import es from 'emoji-picker-react/data/emojis-es';

<EmojiPicker emojiData={es} labels={{ searchPlaceholder: 'Buscar', searchLabel: 'Buscar un emoji' }} />;
```

**Custom emojis** — `customEmojis={[{ id: 'party-parrot', names: ['party parrot'], imgUrl: '/parrot.gif' }]}`; add `group` to give them their own section. See [CUSTOMIZATION.md](CUSTOMIZATION.md).

**Only some categories** — `categories={[Categories.SMILEYS_PEOPLE, Categories.ANIMALS_NATURE]}`.

**Your own suggested emojis** — `suggestedEmojis={['1f44d', '1f389', '1f680']}`.

**Controlled search** — `searchValue` + `onSearchChange`, like an ordinary controlled input.

**Controlled skin tone** — `skinTone` + `onSkinToneChange`.

**Hide the preview / search / skin tones** — `previewConfig={{ showPreview: false }}`, `searchDisabled`, `skinTonesDisabled`.

**Size** — `width` / `height` props; `columns={8}` to fit the width to a number of emojis per row; `--epr-emoji-size` for the emojis themselves.

**Next.js App Router** — import it in any component; the entry is marked `"use client"`. To keep it out of the initial bundle: `const EmojiPicker = dynamic(() => import('emoji-picker-react'), { ssr: false })`.

**Search or look up emojis without the UI** — `import { searchEmojis, getEmojiByUnified } from 'emoji-picker-react/data'`.

**Testing with jsdom / Testing Library** — emojis in the grid have `role="gridcell"` with the emoji name as their accessible name: `getByRole('gridcell', { name: 'grinning face' })`.

## Data API

Framework-free emoji lookup and search, sharing the picker's index:

```js
import { getEmojiByUnified, searchEmojis } from 'emoji-picker-react/data';
import fr from 'emoji-picker-react/data/emojis-fr';

searchEmojis('smile'); // default dataset
searchEmojis('sourire', { emojiData: fr }); // locale dataset
getEmojiByUnified('1f600'); // { unified: '1f600', emoji: '😀', name: 'grinning face', names, variations, addedIn }
```

Both work without React (including in Server Components) and return immutable records. Results follow dataset order and skip picker-only filters such as `hiddenEmojis`, `emojiVersion` and custom emojis. See the [data API contract](docs/v5/DATA_API.md).

## Internationalization

28 emoji datasets ship with the package. Import one and pass it as `emojiData`; translate the remaining UI strings with `labels`. See [INTERNATIONALIZATION.md](INTERNATIONALIZATION.md) for the list.

## Customization

Custom emojis and groups, category icons, preview configuration and CSP nonces: [CUSTOMIZATION.md](CUSTOMIZATION.md).

## Server-side rendering

The picker renders on the server with its styles inlined — no setup. The main and primitives entries are marked `"use client"`, so React Server Components can render them directly; `emoji-picker-react/data` stays server-usable.

## Ready-to-adapt starters

Use the [live gallery](https://ealush.com/emoji-picker-react/#designs) to try designs and copy or download their React and CSS files. Working host integrations include [caret autocomplete](stories/recipes/shortcode-typeahead), [custom-image replies](stories/recipes/community-forum) and [chat insertion](stories/recipes/team-chat).

The [shadcn registry component](registry/emoji-picker.tsx) uses your theme, a native search input, custom cells and the same keyboard engine. Install it with `npx shadcn@latest add https://ealush.com/emoji-picker-react/r/emoji-picker.json` (the item is generated into `website/public/r/emoji-picker.json`). It requires `emoji-picker-react@5` or later. See [the adoption guide](docs/v5/ADOPTION.md) for setup and popup focus behavior.

## Design examples

[`stories/recipes`](stories/recipes) holds 25 production-style designs — ten in-context examples (team chat composer, article comments, status dialog, `:shortcode` typeahead, livestream chat, project icon picker, doc editor panel, community custom emojis, video call reactions, mobile bottom sheet) and fifteen product-inspired builds (Slack, GitHub, Discord, Linear, Notion, Material 3, Teams, WhatsApp, iOS, X, …). Each is available in plain CSS, CSS Modules, Emotion, styled-components, MUI, Tailwind and shadcn/ui, and is screenshot-, axe- and keyboard-tested in every interaction state. All 25 are playable in the [live demo](https://ealush.com/emoji-picker-react/#designs).

<!-- DESIGNS:START (generated by scripts/portDesigns.mts; run `npm run designs`) -->
Every design below is the same picker, recomposed and restyled. [Try them live](https://ealush.com/emoji-picker-react/#designs).

<table>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/team-chat"><img src="docs/designs/team-chat.png" alt="Team chat composer design example" width="260"></a><br><sub><b>Team chat composer</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/article-comments"><img src="docs/designs/article-comments.png" alt="Article comments design example" width="260"></a><br><sub><b>Article comments</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/editor-insert-panel"><img src="docs/designs/editor-insert-panel.png" alt="Doc editor insert panel design example" width="260"></a><br><sub><b>Doc editor insert panel</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/livestream-chat"><img src="docs/designs/livestream-chat.png" alt="Livestream chat design example" width="260"></a><br><sub><b>Livestream chat</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/status-dialog"><img src="docs/designs/status-dialog.png" alt="Set a status dialog design example" width="260"></a><br><sub><b>Set a status dialog</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/shortcode-typeahead"><img src="docs/designs/shortcode-typeahead.png" alt="Shortcode typeahead design example" width="260"></a><br><sub><b>Shortcode typeahead</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/video-call-reactions"><img src="docs/designs/video-call-reactions.png" alt="Video call reactions design example" width="260"></a><br><sub><b>Video call reactions</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/community-forum"><img src="docs/designs/community-forum.png" alt="Community custom emojis design example" width="260"></a><br><sub><b>Community custom emojis</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/project-icon-picker"><img src="docs/designs/project-icon-picker.png" alt="Project icon picker design example" width="260"></a><br><sub><b>Project icon picker</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/habit-tracker-mobile"><img src="docs/designs/habit-tracker-mobile.png" alt="Habit tracker (mobile) design example" width="260"></a><br><sub><b>Habit tracker (mobile)</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/discord-sidebar"><img src="docs/designs/discord-sidebar.png" alt="Discord sidebar design example" width="260"></a><br><sub><b>Discord sidebar</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/slack-reactions"><img src="docs/designs/slack-reactions.png" alt="Slack reactions design example" width="260"></a><br><sub><b>Slack reactions</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/github-reactions"><img src="docs/designs/github-reactions.png" alt="GitHub reactions design example" width="260"></a><br><sub><b>GitHub reactions</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/imessage-tapback"><img src="docs/designs/imessage-tapback.png" alt="iMessage tapback design example" width="260"></a><br><sub><b>iMessage tapback</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/x-composer"><img src="docs/designs/x-composer.png" alt="X composer design example" width="260"></a><br><sub><b>X composer</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/notion-icon-picker"><img src="docs/designs/notion-icon-picker.png" alt="Notion icon picker design example" width="260"></a><br><sub><b>Notion icon picker</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/linear-palette"><img src="docs/designs/linear-palette.png" alt="Linear command palette design example" width="260"></a><br><sub><b>Linear command palette</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/teams-fluent"><img src="docs/designs/teams-fluent.png" alt="Teams (Fluent 2) design example" width="260"></a><br><sub><b>Teams (Fluent 2)</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/material-3"><img src="docs/designs/material-3.png" alt="Material 3 design example" width="260"></a><br><sub><b>Material 3</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/geist-minimal"><img src="docs/designs/geist-minimal.png" alt="Geist minimal design example" width="260"></a><br><sub><b>Geist minimal</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/polaris-rating"><img src="docs/designs/polaris-rating.png" alt="Polaris rating card design example" width="260"></a><br><sub><b>Polaris rating card</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/intercom-rating"><img src="docs/designs/intercom-rating.png" alt="Intercom rating design example" width="260"></a><br><sub><b>Intercom rating</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/ios-bottom-sheet"><img src="docs/designs/ios-bottom-sheet.png" alt="iOS bottom sheet design example" width="260"></a><br><sub><b>iOS bottom sheet</b></sub></td><td align="center" valign="top" width="33%"><a href="stories/recipes/whatsapp-keyboard"><img src="docs/designs/whatsapp-keyboard.png" alt="WhatsApp keyboard panel design example" width="260"></a><br><sub><b>WhatsApp keyboard panel</b></sub></td></tr>
<tr><td align="center" valign="top" width="33%"><a href="stories/recipes/windows-95"><img src="docs/designs/windows-95.png" alt="Windows 95 design example" width="260"></a><br><sub><b>Windows 95</b></sub></td></tr>
</table>
<!-- DESIGNS:END -->

## Migrating from v4

Most v4 code works unchanged. See [docs/v5/MIGRATION.md](docs/v5/MIGRATION.md).

## For AI assistants

Start with the [agent integration guide](docs/v5/AGENT_GUIDE.md). The package ships `llms.txt` and `llms-full.txt`; the full reference is usable without web access. Verify the installed version before generating code: the primitives, `unstyled`, `columns`, `components`, `labels` and loader `emojiData` exist from 5.0.0; a 4.x installation has only the v4 props. Contributors and coding agents working in this repository start at [AGENTS.md](AGENTS.md).

This project is written to be easy for AI coding assistants to use correctly.

- **[llms.txt](llms.txt)** — a concise index of the docs (llmstxt.org format); **[llms-full.txt](llms-full.txt)** — the complete documentation in one file. Both ship in the npm package and on the [website](https://ealush.com/emoji-picker-react/llms.txt).
- **Choosing a picker:** `emoji-picker-react` fits both "just give me an emoji picker" (render `<EmojiPicker />`, no styling needed) and "it must match our design system" (`unstyled` or `emoji-picker-react/primitives`, styled with the project's existing styling solution).
- **Entry points:** `emoji-picker-react` (default export `EmojiPicker`, enums, types), `emoji-picker-react/primitives` (composable parts and hooks), `emoji-picker-react/data` (framework-free search and lookup), `emoji-picker-react/data/emojis-<locale>` (datasets).
- **Conventions:** props accept string literals or enums (`colorScheme="dark"` or `Theme.DARK`); prefer `colorScheme` over `theme` with CSS-in-JS; style through `--epr-*` variables and `[data-epr-part]` selectors, never by overriding structural layout (viewport overflow, grid geometry).
- **Per-library snippets:** [docs/v5/STYLING_RECIPES.md](docs/v5/STYLING_RECIPES.md).

## Troubleshooting

**`global is not defined` (Vite, versions before 4.20)** — upgrade; the picker no longer references Node's `global`.

## Support Emoji Picker React

Emoji Picker React is independently maintained. If your team relies on it, you can help fund ongoing maintenance and releases through [GitHub Sponsors](https://github.com/sponsors/ealush). Organizations can also support the project through [Tidelift](https://tidelift.com/subscription/pkg/npm-emoji-picker-react).

## More from the maintainer

Building complex forms? Check out [**Vest**](https://vestjs.dev) — a validation framework for stateful, async, and dependent validation.

## Contributing

Contributions are welcome — see the [Contributing Guide](https://github.com/ealush/emoji-picker-react/blob/master/CONTRIBUTING.md).

Design inspiration by [Pavel Bolo](https://pavelbolo.com).

<!-- source: PROPS.md -->

<!-- Props reference -->

# Props Reference

Complete list of all props accepted by `EmojiPicker`. All props are optional.

## General Configuration

| Prop              | Type         | Default            | Description                                                                                  |
| ----------------- | ------------ | ------------------ | -------------------------------------------------------------------------------------------- |
| `open`            | `boolean`    | `true`             | Controls the visibility of the picker. While closed it renders nothing but keeps its search, skin tone and reactions-mode state. |
| `colorScheme`     | `Theme`      | `Theme.LIGHT`      | The color scheme. Options: `'light'`, `'dark'`, `'auto'`. Preferred over `theme`, which CSS-in-JS wrappers (Emotion, styled-components, MUI) reserve. |
| `theme`           | `Theme`      | `Theme.LIGHT`      | Alias of `colorScheme`, kept for v4 compatibility.                                           |
| `emojiStyle`      | `EmojiStyle` | `EmojiStyle.NATIVE` | The emoji set to use. Options: `'apple'`, `'google'`, `'facebook'`, `'twitter'`, `'native'`. |
| `emojiVersion`    | `string`     | `null`             | Limit emojis to a specific Unicode emoji version (e.g., `"14.0"`). Native mode additionally filters detected unsupported glyphs, even with this cap set; see [native detection limits](docs/v5/API.md#5c-native-emoji-support-detection). |
| `lazyLoadEmojis`  | `boolean`    | `false`            | If true, emoji images are loaded only when they scroll into view.                            |
| `autoFocusSearch` | `boolean`    | `true`             | Focuses the search input automatically when the picker mounts.                               |
| `emojiData`       | `object \| () => Promise` | `undefined` | Locale dataset, or a loader such as `() => import('emoji-picker-react/data/emojis-fr')` to code-split it. See [INTERNATIONALIZATION.md](INTERNATIONALIZATION.md). |
| `labels`          | `Partial<PickerLabels>` | `undefined` | Localizes every user-facing string (search, results announcements, tabs, reactions, skin tones, loading errors and retry). |

## Dimensions & Styling

| Prop        | Type                 | Default | Description                                           |
| ----------- | -------------------- | ------- | ----------------------------------------------------- |
| `width`     | `string \| number`   | `350`   | Picker width. Numbers are treated as pixels.          |
| `height`    | `string \| number`   | `450`   | Picker height. Numbers are treated as pixels.         |
| `columns`   | `number`             | `undefined` | Emojis per row. The width then fits the columns unless you set `width`; a narrower container shows fewer columns. |
| `style`     | `CSSProperties`      | `{}`    | Inline styles applied to the root element.            |
| `className` | `string`             | `""`    | CSS class applied to the root element.                |
| `unstyled`  | `boolean`            | `false` | Remove the built-in look from every part (colors, borders, rounding, button resets, typography); keep layout, geometry and behavior. Style the parts with `[data-epr-part]` selectors and your own CSS, Tailwind, CSS Modules or CSS-in-JS. Color variables have no effect in this mode; size variables still apply. |
| `cssLayer`  | `string`             | `undefined` | Emit the picker's CSS inside this cascade layer (e.g. `"epr"`). Use with Tailwind v4 or other `@layer` setups and declare it first: `@layer epr, theme, base, components, utilities;`. |
| `components` | `PickerComponents` | `undefined` | Your own components for `Emoji`, `CategoryHeader`, `CategoryButton`, `SkinToneButton`, `ClearButton` and `ExpandButton`. Each receives managed props plus metadata (`emoji`, `category` or `tone`); remove the metadata and spread the rest onto one native element. The picker keeps behavior, accessibility and geometry. See [PRIMITIVES.md](docs/v5/PRIMITIVES.md#parts-and-replacements). |

Theme the built-in look via [CSS variables](CSS_VARIABLES.md). With `unstyled`, style the parts directly; see [the README](README.md#unstyled-your-design-the-supplied-layout).

## Events & Interaction

| Prop                    | Type                                                     | Description                                                                        |
| ----------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `onEmojiClick`          | `(emojiData: EmojiClickData, event: MouseEvent, api: OnEmojiClickApi) => void` | Called when the user selects an emoji (click, or Enter/Space on a focused emoji). `api.collapseToReactions()` returns to the reactions bar. |
| `onReactionClick`       | `(emojiData: EmojiClickData, event: MouseEvent, api: OnEmojiClickApi) => void` | Called when the user selects a reaction in reactions mode.                          |
| `onSkinToneChange`      | `(skinTone: SkinTones) => void`                          | Callback triggered when the user selects a new skin tone.                          |
| `onSearchChange`        | `(value: string) => void`                                | Emitted synchronously with each user search edit (committed, or proposed when `searchValue` is controlled). |
| `onReactionsModeChange` | `(reactionsOpen: boolean) => void`                       | Callback triggered when the picker transitions between reactions mode and the full picker. |

## Search & Categories

| Prop                     | Type                     | Default                   | Description                                                          |
| ------------------------ | ------------------------ | ------------------------- | -------------------------------------------------------------------- |
| `searchDisabled`         | `boolean`                | `false`                   | If true, the search bar is completely removed.                       |
| `searchPlaceholder`      | `string`                 | `"Search"`                | Placeholder text for the search input.                               |
| `searchLabel`            | `string`                 | _(English default)_       | Accessible label for the search input.                               |
| `searchClearButtonLabel` | `string`                 | `"Clear"`                 | Aria label for the search clear button.                              |
| `searchValue`            | `string`                 | `undefined`               | Controlled search value (raw text). User edits emit `onSearchChange` proposals; the parent decides what is accepted. |
| `defaultSearchValue`     | `string`                 | `undefined`               | Uncontrolled initial search value, read once per mounted lifetime.   |
| `categories`             | `(Categories \| CategoryConfig)[]` | _(All)_         | Categories to show, in order: `Categories` values or `{ category, name, icon?, group? }` objects. |
| `suggestedEmojisMode`    | `SuggestionMode`         | `SuggestionMode.FREQUENT` | Logic for "Suggested" category. Options: `'recent'`, `'frequent'`.   |
| `suggestedEmojis`        | `string[]`               | `undefined`               | Caller-defined Suggested category contents/order: unified IDs, custom emoji IDs or emoji characters. While present, `suggestedEmojisMode` is ignored for contents. |
| `defaultSkinTone`        | `SkinTonesValue`         | `'neutral'`               | The initial skin tone: `SkinTones` enum or its value (`'neutral'`, `'1f3fb'`, `'1f3fc'`, `'1f3fd'`, `'1f3fe'`, `'1f3ff'`). |
| `skinTone`               | `SkinTonesValue`         | `undefined`               | Controlled skin tone (pair with `onSkinToneChange`).                 |
| `skinTonesDisabled`      | `boolean`                | `false`                   | If true, users cannot change the skin tone.                          |
| `skinTonePickerLocation` | `SkinTonePickerLocation` | `SEARCH`                  | Location of the skin tone trigger. Options: `'SEARCH'`, `'PREVIEW'`, `'NONE'`. When the chosen region is absent (`searchDisabled`, or `previewConfig.showPreview: false`) the control moves to the other region, or is off when neither exists. |

## Customization & Advanced

| Prop            | Type                                             | Default                 | Description                                                              |
| --------------- | ------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------ |
| `customEmojis`  | `CustomEmoji[]`                                  | `[]`                    | Array of custom image-based emojis to inject. See [CUSTOMIZATION.md](CUSTOMIZATION.md). |
| `hiddenEmojis`  | `string[]`                                       | `[]`                    | Array of unified IDs (e.g., `'1f921'`) or custom emoji ids to hide from the picker. Case-insensitive. |
| `previewConfig` | `PreviewConfig`                                  | `{ showPreview: true }` | Configuration for the bottom preview bar. See [CUSTOMIZATION.md](CUSTOMIZATION.md). |
| `getEmojiUrl`   | `(unified: string, style: EmojiStyle) => string` | -                       | Function to override the default CDN URL for emoji images.               |
| `categoryIcons` | `CategoryIcons`                                  | `{}`                    | Map `Categories` enum values to custom React nodes for navigation icons. See [CUSTOMIZATION.md](CUSTOMIZATION.md). |
| `nonce`         | `string`                                         | `undefined`             | Content Security Policy (CSP) nonce for the inline style tag. See [CUSTOMIZATION.md](CUSTOMIZATION.md). |

## Reactions Picker Mode

| Prop                   | Type       | Default         | Description                                                              |
| ---------------------- | ---------- | --------------- | ------------------------------------------------------------------------ |
| `reactionsDefaultOpen` | `boolean`  | `false`         | If true, mounts in "Reactions" mode (single row) instead of full picker. |
| `reactions`            | `string[]` | _(Default Set)_ | Emojis for the reactions bar: unified IDs (`'1f44d'`) or the characters themselves (`'👍'`). |
| `allowExpandReactions` | `boolean`  | `true`          | If true, shows a `+` button to switch from reactions to full picker.     |

### Default picker root attributes

`EmojiPicker` accepts `id`, `title`, `lang`, `dir`, `aria-*` and `data-*` identifying
attributes on its root, alongside `className` and `style`. Its public types include
the named attributes and React ARIA attributes. The library reserves `role` and
`data-epr-*`; use a wrapper or primitives for other native event handlers.

<!-- source: CSS_VARIABLES.md -->

<!-- CSS variables -->

# 🎨 CSS Variables

You can customize specific parts of the picker by overriding these CSS variables on a class you pass through `className` (or `.EmojiPickerReact`). The picker declares its tokens at zero specificity (`:where()`), so any selector of yours wins — no specificity tricks or `!important`. Want the default look? Change nothing: these variables only fine-tune it.

**Color variables theme the built-in look.** With the `unstyled` prop (or a bare primitives `Root`) the built-in look is removed, so color variables have no effect; style the `[data-epr-part]` selectors directly instead (see the [README](README.md#unstyled-your-design-the-supplied-layout)). Size variables such as `--epr-emoji-size` apply in every mode.

```css
.EmojiPickerReact {
  --epr-emoji-size: 32px;
}
```

or

```css
aside.EmojiPickerReact {
  --epr-emoji-size: 32px;
}
```

## 🎛️ General Variables

| Variable                     | Description                                        | Default   |
| :--------------------------- | :------------------------------------------------- | :-------- |
| `--epr-font-family`          | Font family of the picker's text.                  | `sans-serif` |
| `--epr-emoji-size`           | Size of the emojis.                                | `30px`    |
| `--epr-emoji-padding`        | Padding around each emoji.                         | `5px`     |
| `--epr-emoji-gap`            | **Deprecated**. Use `--epr-emoji-padding` instead. | -         |
| `--epr-bg-color`             | Background color of the picker.                    | `#fff`    |
| `--epr-text-color`           | Main text color.                                   | `#6b6b6b` |
| `--epr-picker-border-color`  | Border color of the picker container.              | `#e7e7e7` |
| `--epr-picker-border-radius` | Border radius of the picker.                       | `8px`     |
| `--epr-horizontal-padding`   | Horizontal padding for various elements.           | `10px`    |
| `--epr-highlight-color`      | Color for active states and highlights.            | `#007aeb` |
| `--epr-hover-bg-color`       | Background color on hover.                         | `#e5f0fa` |
| `--epr-focus-bg-color`       | Background color on focus.                         | `#e0f0ff` |

## 🔎 Search Input

| Variable                               | Description                             | Default                            |
| :------------------------------------- | :-------------------------------------- | :--------------------------------- |
| `--epr-search-input-bg-color`          | Background color of the search input.   | `#f6f6f6`                          |
| `--epr-search-input-bg-color-active`   | Background color when search is active. | `var(--epr-search-input-bg-color)` |
| `--epr-search-input-text-color`        | Text color in the search input.         | `var(--epr-text-color)`            |
| `--epr-search-input-placeholder-color` | Placeholder text color.                 | `var(--epr-text-color)`            |
| `--epr-search-border-color`            | Border color of the search input.       | `var(--epr-search-input-bg-color)` |
| `--epr-search-border-color-active`     | Border color when search is active.     | `var(--epr-highlight-color)`       |
| `--epr-search-input-border-radius`     | Border radius of the search input.      | `8px`                              |
| `--epr-search-input-height`            | Height of the search input.             | `40px`                             |
| `--epr-search-icon-color`              | Color of the search icon.               | -                                  |

## 🏷️ Category Navigation

| Variable                                | Description                                                     | Default             |
| :-------------------------------------- | :-------------------------------------------------------------- | :------------------ |
| `--epr-category-navigation-button-size` | Size of category navigation buttons.                            | `30px`              |
| `--epr-category-icon-active-color`      | Color of the active/hovered category icon (and focus ring).     | `#3371B7` (`#6AA9DD` in dark theme) |
| `--epr-category-icon-inactive-color`    | Color of inactive category icons.                               | `#868686` (`#C0C0BF` in dark theme) |

## 📃 Category Labels

| Variable                          | Description                                    | Default                 |
| :-------------------------------- | :--------------------------------------------- | :---------------------- |
| `--epr-category-label-bg-color`   | Background color of the sticky category label. | `#ffffffe6`             |
| `--epr-category-label-text-color` | Text color of the category label.              | `var(--epr-text-color)` |
| `--epr-category-label-height`     | Height of the category label.                  | `40px`                  |

## 👁️ Preview Area

| Variable                   | Description                            | Default                 |
| :------------------------- | :------------------------------------- | :---------------------- |
| `--epr-preview-height`     | Height of the preview area.            | `70px`                  |
| `--epr-preview-emoji-size` | Size of the preview emoji.             | `45px`                  |
| `--epr-preview-text-size`  | Font size of text in the preview area. | `14px`                  |
| `--epr-preview-text-color` | Text color in the preview area.        | `var(--epr-text-color)` |

## 😀 Native Emoji Font

| Variable                 | Description                                                                 | Default                       |
| :----------------------- | :-------------------------------------------------------------------------- | :---------------------------- |
| `--epr-emoji-font-family` | Font stack for native emojis (e.g. add a country-flag polyfill font first). Native support detection measures this font. | platform emoji fonts |

## 🖐️ Skin Tone Picker

| Variable                            | Description                                    | Default     |
| :---------------------------------- | :--------------------------------------------- | :---------- |
| `--epr-skin-tone-picker-menu-color` | Background color of the skin tone picker menu. | `#ffffff95` |
| `--epr-skin-tone-size`              | Size of skin tone circles.                     | `20px`      |

## 🌑 Dark Mode

| Variable                           | Description                           | Default                      |
| :--------------------------------- | :------------------------------------ | :--------------------------- |
| `--epr-dark-bg-color`              | Background color in dark mode.        | `#222222`                    |
| `--epr-dark-picker-border-color`   | Border color in dark mode.            | `#151617`                    |
| `--epr-dark-text-color`            | Text color in dark mode.              | `var(--epr-highlight-color)` |
| `--epr-dark-search-input-bg-color` | Search input background in dark mode. | `#333333`                    |
| `--epr-dark-hover-bg-color`        | Hover background color in dark mode.  | `#363636f6`                  |

<!-- source: CUSTOMIZATION.md -->

<!-- Customization -->

# Customization

For an agent-assisted starting point, copy the [brand styling](docs/v5/PROMPTS.md#match-my-brand)
or [design-library composition](docs/v5/PROMPTS.md#build-with-my-design-library) prompt.

## Custom Emojis

Pass the `customEmojis` prop to inject image-based emojis. Each entry uses this structure:

```ts
{
  id: string;      // Unique ID
  names: string[]; // Search keywords
  imgUrl: string;  // Image source
  group?: string;  // Optional section; see grouping below
}
```

```jsx
<EmojiPicker
  customEmojis={[
    {
      id: 'panda',
      names: ['panda', 'bear'],
      imgUrl: 'https://example.com/panda.png',
    },
  ]}
/>
```

### 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. The example below
places two groups and the ungrouped bucket.

### 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`:

```ts
{
  defaultEmoji: string; // Default: "1f60a"
  defaultCaption: string; // Default: "What's your mood?"
  showPreview: boolean; // Default: true
}
```

## Custom Category Icons

Customize the navigation icons using one of three methods.

**Method 1: Recolor the default icons with CSS variables**

The default icons follow two variables. Set them on the picker root via
the `style` prop (the picker defines its own defaults on `.epr-main`, so
values inherited from outer ancestors are shadowed):

```tsx
<EmojiPicker
  style={
    {
      '--epr-category-icon-active-color': '#e11d48',
      '--epr-category-icon-inactive-color': '#a8a29e',
    } as React.CSSProperties
  }
/>
```

| Variable                             | Default                             |
| :----------------------------------- | :---------------------------------- |
| `--epr-category-icon-active-color`   | `#3371B7` (`#6AA9DD` in dark theme) |
| `--epr-category-icon-inactive-color` | `#868686` (`#C0C0BF` in dark theme) |

**Method 2: The `categoryIcons` prop**

Map `Categories` enum values to React nodes:

```tsx
import EmojiPicker, { Categories } from 'emoji-picker-react';

<EmojiPicker
  categoryIcons={{
    [Categories.SUGGESTED]: <img src="recent.png" alt="Recent" />,
    [Categories.SMILEYS_PEOPLE]: <MyCustomFaceIcon />,
  }}
/>;
```

**Method 3: The `categories` configuration array**

Define the icon directly within the category configuration object:

```tsx
import EmojiPicker, { Categories } from 'emoji-picker-react';

<EmojiPicker
  categories={[
    {
      category: Categories.SUGGESTED,
      name: 'Recently Used',
      icon: <img src="recent.png" alt="Recent" />,
    },
    {
      category: Categories.SMILEYS_PEOPLE,
      name: 'Smileys & People',
      icon: <MyCustomFaceIcon />,
    },
  ]}
/>;
```

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)

If your site has a CSP that blocks inline styles, pass a `nonce` to the `EmojiPicker` component. It is applied to the inline `<style>` tag:

```jsx
<EmojiPicker nonce="your-nonce-value" />
```

<!-- source: INTERNATIONALIZATION.md -->

<!-- Internationalization -->

# Internationalization (i18n)

Import the dictionary you need and pass it to the `emojiData` prop:

```tsx check
import * as React from 'react';
import EmojiPicker from 'emoji-picker-react';
import es from 'emoji-picker-react/data/emojis-es'; // Spanish

function App() {
  return <EmojiPicker emojiData={es} />;
}
```

To defer the additional locale to a separate chunk, pass a loader instead. The default entry still eagerly registers English; the picker shows its loading state until the selected locale resolves:

```tsx check
import * as React from 'react';
import EmojiPicker from 'emoji-picker-react';

const loadSpanish = () => import('emoji-picker-react/data/emojis-es');

export function App() {
  return <EmojiPicker emojiData={loadSpanish} />;
}
```

To avoid eager English registration, use only the primitives entry for the picker and its runtime constants. Supply the locale loader explicitly; its dataset remains deferred. Importing the default entry elsewhere in the same application still registers English.

```tsx check
import * as React from 'react';
import {
  Root, Search, CategoryNav, Viewport, List, Empty, Loading, LoadError, Preview,
} from 'emoji-picker-react/primitives';

const loadSpanish = () => import('emoji-picker-react/data/emojis-es');

export function SpanishPicker() {
  return (
    <Root appearance="default" emojiData={loadSpanish} style={{ width: 350 }}>
      <Search />
      <CategoryNav />
      <Viewport style={{ height: 320 }}>
        <List />
        <Empty />
        <Loading />
        <LoadError />
      </Viewport>
      <Preview />
    </Root>
  );
}
```

Category names follow the dataset; translate the remaining UI strings (search label, results announcements, tabs, reactions, skin tones, loading, loadingError and retryLoading) with the `labels` prop. The legacy `emoji-picker-react/dist/data/emojis-*` paths still resolve.

## Supported Languages

- `emojis-bn` (Bengali)
- `emojis-da` (Danish)
- `emojis-de` (German)
- `emojis-en-gb` (English, GB)
- `emojis-en` (English, US)
- `emojis-es-mx` (Spanish, Mexico)
- `emojis-es` (Spanish)
- `emojis-et` (Estonian)
- `emojis-fi` (Finnish)
- `emojis-fr` (French)
- `emojis-hi` (Hindi)
- `emojis-hu` (Hungarian)
- `emojis-it` (Italian)
- `emojis-ja` (Japanese)
- `emojis-ko` (Korean)
- `emojis-lt` (Lithuanian)
- `emojis-ms` (Malay)
- `emojis-nb` (Norwegian Bokmal)
- `emojis-nl` (Dutch)
- `emojis-pl` (Polish)
- `emojis-pt` (Portuguese)
- `emojis-ru` (Russian)
- `emojis-sv` (Swedish)
- `emojis-th` (Thai)
- `emojis-uk` (Ukrainian)
- `emojis-vi` (Vietnamese)
- `emojis-zh-hant` (Traditional Chinese)
- `emojis-zh` (Simplified Chinese)

<!-- source: docs/v5/ADOPTION.md -->

<!-- Adoption -->

# Adopting v5

Choose batteries included or BYOD — bring your own design, design language and design library — with one shared picker engine, with custom image emoji, custom groups, reactions, localization and the same keyboard engine in both modes.

## Native search in your design system

```tsx
import * as Picker from 'emoji-picker-react/primitives';

<Picker.Root style={{ height: 400 }}>
  <Picker.Panel className="flex flex-col gap-2">
    <Picker.SearchInput as={Input} placeholder="Search emoji" />
    <Picker.Viewport>
      <Picker.List />
      <Picker.Empty />
      <Picker.Loading />
      <Picker.LoadError />
    </Picker.Viewport>
  </Picker.Panel>
</Picker.Root>
```

`Input` must forward its ref and native input props to one `<input>`. Root controls search; use Root’s `searchValue` / `onSearchChange` for controlled state. SearchInput’s ref/className/placeholder address the input directly. Use Search for the managed input/icon/clear-button region instead. They register the same single search region and share IME, filtering and keyboard behavior.

Custom input props are inferred from `as`, including required design-library options (for example `variant`) and native-name overrides such as `size="sm"`. Native search event handlers keep their input event types. Native tags other than `input` are excluded from the API. Put layout props on an explicit Panel between Root and its expanded parts. Panel owns its collapsed hidden/inert behavior. Custom emoji cells receive `emoji.isActive` and `data-epr-active`; preserve all managed button props and position styles. Custom cells and category headers own decorative styles; they do not inherit the default button reset or header typography. Provide a visible keyboard focus state.

### Inputs with a wrapper ref, including MUI

Some libraries put `ref`, `className` or ARIA props on a wrapper. Adapt them before using `as`: the picker needs the native input for focus, IME and region navigation. For MUI TextField, route native attributes through [`slotProps.htmlInput`](https://mui.com/material-ui/react-text-field/#controlling-the-html-input), and use `inputRef` for the input ref:

```tsx
import * as React from 'react';
import TextField from '@mui/material/TextField';

const MuiInput = React.forwardRef<
  HTMLInputElement,
  React.InputHTMLAttributes<HTMLInputElement> & {
    variant: 'outlined' | 'filled';
  }
>(function MuiInput(
  { variant, value, onChange, disabled, autoFocus, placeholder, ...native },
  ref,
) {
  return (
    <TextField
      variant={variant}
      value={value}
      onChange={onChange}
      disabled={disabled}
      autoFocus={autoFocus}
      placeholder={placeholder}
      inputRef={ref}
      slotProps={{ htmlInput: native }}
      size="small"
      fullWidth
    />
  );
});

// Inside Picker.Root:
<Picker.SearchInput as={MuiInput} variant="outlined" />;
```

Use the slot API of your installed MUI version. Keep the picker-supplied composition handlers, value, type and native attributes on the input. MUI buttons also need `minWidth: 0` and padding compatible with the managed square cell; spread the managed position style and className. Set the library's `color` explicitly when spreading native button props, since MUI narrows that prop to its palette names. The [complete executable MUI composition](../../stories/v5/MuiComposition.tsx) includes bordered Button cells and Typography headers; its types and cross-browser keyboard, measurement and axe behavior are checked in this repository.

## Dataset recovery and full localization

```tsx
const loadFrench = ({ signal }: Picker.EmojiDataLoaderOptions) =>
  fetch('/emoji-fr.json', { signal }).then(response => {
    if (!response.ok) throw new Error('Dataset request failed');
    return response.json();
  });

<Picker.Root emojiData={loadFrench} labels={{
  searchLabel: 'Rechercher un emoji', searchPlaceholder: 'Rechercher',
  loading: 'Chargement…', loadingError: 'Chargement impossible.',
  retryLoading: 'Réessayer',
}}>{/* SearchInput, Viewport, List, Loading and LoadError */}</Picker.Root>
```

Hoist the loader. Retry starts a new attempt; source changes and unmount abort the old attempt. Conditionally mount Root to control loading lifetime; an unmounted Root starts no loads. Malformed loader payloads enter the same recoverable error state. Late successes or failures cannot overwrite a newer source. `useEmojiDataState()` exposes `{ loading, error, retry }` inside Root when an application owns recovery UI.

Emoji names/categories come from any of the 28 bundled datasets or your own data. Translate the remaining visible and announced strings through `labels`, category names through `categories`, and the preview caption through `previewConfig.defaultCaption`. This includes loading failure and retry text.

## shadcn registry

`registry/emoji-picker.tsx` is the consumer component; `npm run registry` embeds it in `website/public/r/emoji-picker.json`, which the website publishes. Install it with:

```sh
npx shadcn@latest add https://ealush.com/emoji-picker-react/r/emoji-picker.json
```

The registry item depends on `emoji-picker-react@^5.0.0`. The registry component styles its search input, tabs, emoji cells, headers, tone button and variations menu with your shadcn theme classes (`bg-popover`, `bg-accent`, `border-input`, …) through `components` and `[data-epr-part]` variants, so it follows light, dark and custom themes. The picker keeps behavior and cell geometry. Wrap it in your existing Popover:

```tsx
<Popover open={open} onOpenChange={setOpen}>
  <PopoverTrigger aria-label="Insert emoji">😊</PopoverTrigger>
  <PopoverContent aria-label="Choose an emoji">
    <EmojiPicker onEmojiClick={emoji => {
      insertAtCaret(emoji);
      setOpen(false);
    }} />
  </PopoverContent>
</Popover>
```

The host owns insertion and dismissal. The Popover restores trigger focus. Escape first closes an open variation/tone menu, then a subsequent Escape reaches the host. The light/dark Storybook examples import the registry component itself; browser checks exercise search, keyboard insertion, dismissal, focus restoration and WCAG-tagged axe rules.

## Working starter sources

The website gallery’s “Get the code” control fetches React/CSS/CSS Modules source only when requested. Copy or download the composition and styles, then adapt the host callback:

- Shortcode typeahead: editable textarea, query at the caret, token replacement, suffix preservation, ArrowDown/Enter acceptance and Escape dismissal. This is name autocomplete; canonical Slack alias conversion is not promised.
- Community reply: custom images select a host-owned `:id:` token at the textarea selection.
- Team chat: inserts at the input selection and closes the picker.

All 25 designs share a source generator. Their seven styling-stack variants remain covered by visual equivalence tests.

## Startup accounting

Import runtime constants from `/primitives`. Runtime imports from the main or `/data` entry register the synchronous default dataset, so those mixed graphs intentionally have a larger initial payload.

The configured minimal consumer, bundled from an installed package tarball, must stay within **34 KiB initial gzip including ShipStyles**, with the dataset deferred. Unused parts, icons and styles can be removed by the consumer bundler; the default picker retains its complete composition. The complete-runtime regression cap is **34 KiB**, down from 41 KiB after the original 40.5 KiB adoption candidate. Earlier gates that excluded ShipStyles are not comparable. Reducing the runtime toward 25 KiB remains profiling work. Account for initial JavaScript and dataset traffic separately.

<!-- source: docs/v5/API.md -->

<!-- v5 API -->

# v5 API reference

Choose batteries included or BYOD (bring your own design, design language and design library). Both use the same behavior engine. The v5 public API is designed from the consumer inward:

- `<EmojiPicker />` remains the primary path;
- v4 source compatibility is preserved wherever the architecture does not require a break;
- new APIs are added only for demonstrated needs;
- composition is layered: rearrange the macro structure, read picker state through hooks, and — when a brand needs it — replace the markup of emoji cells and category headers while the library keeps owning their behavior.

## 1. Batteries included

```tsx
import EmojiPicker from 'emoji-picker-react';

function Composer() {
  return <EmojiPicker onEmojiClick={handleEmoji} />;
}
```

Consumers do not need primitives to upgrade to v5.

## 2. Additions to the default picker

v5 adds:

```ts
type EmojiPickerV5Additions = {
  searchValue?: string;
  defaultSearchValue?: string;
  onSearchChange?: (value: string) => void;
  searchLabel?: string;

  suggestedEmojis?: string[];

  onReactionsModeChange?: (reactionsOpen: boolean) => void;

  labels?: Partial<PickerLabels>;   // §5a
  skinTone?: SkinTonesValue;        // §5b, controlled
  unstyled?: boolean;               // §11
  columns?: number;                 // §11a
  components?: PickerComponents;    // shared managed-control replacements
  emojiData?: EmojiData | EmojiDataLoader; // §12a, loader form is new
};
```

`skinTonePickerLocation` also accepts `SkinTonePickerLocation.NONE` (§8).

The assembled picker retains its legacy visibility and placement props; see [PROPS.md](../../PROPS.md). Those switches are not primitive Root props.

## 3. Literal values without removing enums

v5 accepts readable literals:

```tsx
<EmojiPicker
  theme="dark"
  emojiStyle="apple"
  suggestedEmojisMode="frequent"
/>
```

Existing enum-based code remains valid:

```tsx
<EmojiPicker
  theme={Theme.DARK}
  emojiStyle={EmojiStyle.APPLE}
  suggestedEmojisMode={SuggestionMode.FREQUENT}
/>
```

Existing enum exports remain part of v5.

## 4. Controlled search

```tsx
function ControlledPicker() {
  const [search, setSearch] = useState('');

  return (
    <EmojiPicker
      searchValue={search}
      onSearchChange={setSearch}
    />
  );
}
```

Uncontrolled:

```tsx
<EmojiPicker defaultSearchValue="party" />
```

The visible value and callback use raw user text. Filtering uses a normalized derived query and is debounced; see [primitive state and actions](./PRIMITIVES.md#state-and-actions).

Type-to-search differs slightly between controlled and uncontrolled usage:

- both modes: focus Search immediately, then behave like ordinary input editing;
- controlled: the keystroke is a proposal like any other edit, so a parent that ignores it simply leaves the value unchanged — the same thing that happens when you type into a controlled input whose parent ignores you;
- focus transfer is never conditional on acceptance.

If Search is omitted, built-in type-to-search behaves like `searchDisabled`, while an external application input may still drive filtering through controlled `searchValue`.

## 5. Search accessibility label

The search input's accessible label, an English constant in v4, is configurable:

```tsx
<EmojiPicker
  searchPlaceholder="Buscar"
  searchLabel="Buscar un emoji"
/>
```

`searchLabel` defaults to the v4 English label, so plug-and-play behavior is unchanged.

Primitive consumers may also supply a consumer `aria-label` through Search `inputProps`; when supplied there, that explicit primitive-level label wins for that Search instance.

## 5a. Localize every string

`labels` covers every user-facing string the picker renders or announces. Omitted keys keep their English (v4) defaults; `labels` wins over the individual `searchPlaceholder`/`searchLabel`/`searchClearButtonLabel` props, which keep working.

```tsx
<EmojiPicker
  emojiData={es}
  labels={{
    searchPlaceholder: 'Buscar',
    searchLabel: 'Buscar un emoji',
    searchClear: 'Borrar',
    searchResultsNone: 'Sin resultados',
    searchResultsOne: '1 resultado.',
    searchResultsMany: '%n resultados.',
    categoryNavigation: 'Categorías',
    reactions: 'Reacciones',
    expandReactions: 'Ver todos',
    loading: 'Cargando…',
    loadingError: 'No se pudieron cargar los emojis.',
    retryLoading: 'Reintentar',
    skinToneNeutral: 'Tono neutro',
    // skinToneLight, skinToneMediumLight, skinToneMedium,
    // skinToneMediumDark, skinToneDark
  }}
/>
```

Category names come from the localized `emojiData` (or `categories`); the preview caption from `previewConfig.defaultCaption`.

## 5b. Controlled skin tone

```tsx
const [tone, setTone] = useState(SkinTones.NEUTRAL);

<EmojiPicker skinTone={tone} onSkinToneChange={setTone} />
```

While `skinTone` is present it is the source of truth (`defaultSkinTone` is ignored); choosing a tone reports through `onSkinToneChange`.

## 5c. Native emoji support detection

`emojiStyle` defaults to `native`. Native glyphs come from the installed emoji font, which can lag behind the dataset. The picker probes that font on the client and hides:

- emojis newer than the platform renders (they would show as empty boxes);
- individual country flags where the installed font has no flag glyph;
- individual missing glyphs, broken join/modifier sequences, and subdivision flags that fall back to a plain black flag.

Detection never delays the first paint. Before paint, the picker draws one sample per emoji version and a country flag, and hides versions (and country and subdivision flags) the font cannot draw. Exact checks then run only for identities about to be shown: grid cells within a viewport of the visible rows (in either scroll direction) with their skin tone variants, and the reaction choices. They run in small batches between tasks and are cached, so each glyph is checked at most once per font; the rest of the inventory keeps its version prediction. When a check disagrees with the prediction the picker rerenders; otherwise nothing changes. Pending keyboard or tab navigation is never cancelled by these results. Filtering precedes grid layout, so removed cells leave no gaps; search result counts use the same filtered inventory. Reactions and the variation menu also omit unavailable choices, and the managed Preview does not draw unsupported native glyphs. This applies to both the default picker and primitives. Image styles and image-based custom emojis do not depend on OS glyph support.

`emojiVersion` remains an additional maximum version: it never disables native detection or makes unsupported glyphs available. SSR and hydration-first output stay deterministic; detection is client-only. The standalone `Emoji` component outside a picker Root does not participate in Root inventory filtering.

Detection is heuristic, not a browser-provided glyph-coverage guarantee. It compares rendered width and canvas artwork under two text colors, which distinguishes ordinary missing-glyph/text fallback from fixed-color emoji artwork, including black-and-white artwork. Unusual fonts may be misclassified. Inconclusive sequence probes preserve those entries. If canvas readback is blocked or no stable emoji artwork baseline is available, the picker preserves the whole inventory rather than hiding everything. Avoid promising complete suppression in those environments.

Results are cached per document, font and sequence. Bounded canvas batches share pixel readbacks; later pickers on the same page reuse cached results without probing again. A flag polyfill font can be supplied through `--epr-emoji-font-family`; detection measures that same font.

Detection follows font changes selected by attributes on Root or its ancestors (including `class`, `style`, and `data-theme`), even when those fonts are already loaded. It also re-checks in the background after webfonts finish loading, keeping the current results on screen until the new ones are ready.

## 6. Observe reactions/full-picker mode

```tsx
<EmojiPicker
  reactionsDefaultOpen
  onReactionsModeChange={(reactionsOpen) => {
    updateLayout(reactionsOpen);
  }}
/>
```

This is an observer, not a second controlled mode API.

Existing `reactionsDefaultOpen`, `allowExpandReactions`, `reactions`, `onReactionClick`, and `collapseToReactions()` remain.

## 7. Caller-defined suggestions

```tsx
<EmojiPicker
  suggestedEmojis={[
    '1F601',
    '1f44d-1f3fd',
    '1F603',
  ]}
/>
```

For standard emoji IDs:
- matching is case-insensitive;
- a valid variation remains that exact variation for rendering rather than collapsing to the neutral base emoji;
- duplicates are removed by canonical normalized ID, first occurrence wins.

Custom emoji IDs use the same case-insensitive rule — `customEmojis` are already lowercased when indexed, so there is no separate exact-match pass.

Entries may be unified IDs, custom emoji IDs, or the emoji characters themselves (`'🧠'`, `'❤️'`), so recents stored as inserted text can be passed through unchanged; unknown entries are ignored.

When `suggestedEmojis` is supplied, it determines the Suggested category contents/order. `suggestedEmojisMode` remains relevant only when `suggestedEmojis` is absent.

See [primitive state and actions](./PRIMITIVES.md#state-and-actions).

## 8. Structural primitives

```tsx
import * as EmojiPicker from 'emoji-picker-react/primitives';

function ProductPicker() {
  return (
    <EmojiPicker.Root>
      <div className="my-card">
        <EmojiPicker.CategoryNav />

        <div className="my-header">
          <MyBrand />
          <button type="button">Close</button>
          <EmojiPicker.Search />
        </div>

        <EmojiPicker.Viewport>
          <EmojiPicker.List />
        </EmojiPicker.Viewport>

        <EmojiPicker.Preview />
      </div>
    </EmojiPicker.Root>
  );
}
```

Root renders exactly the children supplied by the caller. It never inserts Panel, Reactions, Search, Preview or SkinTone. There is no composition switch. A full-picker-only layout may omit Panel. For compact reactions mode, place Reactions outside Panel and put the expanded content inside Panel so its hidden/inert state follows the mode.

```tsx check
import * as React from 'react';
import * as Picker from 'emoji-picker-react/primitives';

export function ReactionPicker({ open }: { open: boolean }) {
  if (!open) return null;
  return (
    <Picker.Root reactionsDefaultOpen style={{ width: 350, height: 450 }}>
      <Picker.Reactions />
      <Picker.Panel className="my-panel" style={{ gap: 8 }}>
        <Picker.Search><Picker.SkinTone /></Picker.Search>
        <Picker.CategoryNav />
        <Picker.Viewport>
          <Picker.List />
          <Picker.Empty />
          <Picker.Loading />
          <Picker.LoadError />
        </Picker.Viewport>
        <Picker.Preview />
      </Picker.Panel>
    </Picker.Root>
  );
}
```

Conditional mounting controls whether a Root exists. Omit Search/SearchInput, Preview or SkinTone to omit that UI; `open`, `searchDisabled`, `skinTonesDisabled`, `skinTonePickerLocation` and `previewConfig.showPreview` belong to the assembled default picker. `composition` and `panelProps` are unsupported. Put layout and native attributes directly on Panel.

The full primitive grammar, props, refs, native prop forwarding and validation behavior are documented in [PRIMITIVES.md](./PRIMITIVES.md).

### Exports

Parts:

- `Root`
- `Panel` — expanded content with managed hidden/inert presence
- `Reactions` — compact reaction controls
- `Search`
- `SearchInput` — native input / ref-forwarding design-system input
- `LoadError` — localized recoverable loader failure
- `CategoryNav`
- `Viewport`
- `List`
- `Preview`
- `Empty` — renders while an applied search shows nothing (§10a)
- `Loading` — renders while the dataset loads (§12a)
- `SkinTone` — the skin tone control, placed anywhere (§10b)

Hooks (call inside `Root`):

- `useActiveEmoji()` — the hovered/focused emoji, in `onEmojiClick`'s shape
- `useSkinTone()` — `[tone, setTone]`; the setter reports `onSkinToneChange`
- `useSearchState()` — `{ search, resultCount }`
- `useSearchActions()` — `{ setValue, clear }`
- `useCategoryNavigation()` — `{ categories, activeCategory, jumpToCategory }`
- `usePickerMode()` — `{ reactionsOpen, canExpand, expand, collapse }`
- `useEmojiDataState()` — `{ loading, error, retry }`

Tokens (plain data): `structuralPickerTokens`, `lightPickerTokens`, `darkPickerTokens`, `defaultPickerTokens`.

Panel and Reactions are exported parts. Rendering Reactions opts into the compact UI, while `reactionsDefaultOpen`, `allowExpandReactions` and the mode actions control behavior. Rendering a part never requires a secondary presence switch.

## 9. Custom emoji cells and category headers

Branded designs often need different markup, not just different CSS. `List` accepts `components` for emoji cells and category headers. The library still owns their behavior: each component receives the library-owned props and must spread them onto its element.

```tsx
import * as EmojiPicker from 'emoji-picker-react/primitives';

// Define components outside render: a new identity remounts every cell.
function Cell({ emoji, children, ...props }: EmojiPicker.EmojiRenderProps) {
  return (
    <button {...props} className={`${props.className} my-cell`}>
      {children /* the default glyph/image, or render emoji.emoji */}
      {emoji.hasVariations ? <span className="my-dot" /> : null}
    </button>
  );
}

function Header({ category, ...props }: EmojiPicker.CategoryHeaderRenderProps) {
  return <h3 {...props}>{category.name}</h3>;
}

<EmojiPicker.List components={{ Emoji: Cell, CategoryHeader: Header }} />
```

- `Emoji` must render a `<button>` carrying the provided `type`, `className`, `style` (virtualized position), `tabIndex`, `aria-label` and `data-epr-*` props. Its content may nest arbitrarily; clicks anywhere inside select the emoji.
- `emoji` (`ListEmoji`): `unified` (the exact rendered identity), `names`, `emoji` (native text), `isCustom`, `imageUrl` (undefined for standard native emojis; active image style URL otherwise, custom `imgUrl` for custom emojis), `hasVariations`.
- `CategoryHeader` receives the sticky, measured label's `className` and `data-epr-part`; `category` is `{ id, name }`.

There is still no render-prop over the whole list: virtualization, ordering and grid semantics stay library-owned.

## 10. Valid composition

```tsx
<EmojiPicker.Root>
  <header>
    <EmojiPicker.Search />
    <EmojiPicker.CategoryNav />
  </header>

  <EmojiPicker.Viewport>
    <EmojiPicker.List />
  </EmojiPicker.Viewport>

  <EmojiPicker.Preview />
</EmojiPicker.Root>
```

Also valid:

```tsx
<EmojiPicker.Root searchValue={externalSearch}>
  <MyExternalSearchControls />
  <EmojiPicker.Viewport>
    <EmojiPicker.List />
  </EmojiPicker.Viewport>
</EmojiPicker.Root>
```

Here Search is omitted, so built-in type-to-search is disabled, but the controlled `searchValue` still filters List.

Invalid:

```tsx
<EmojiPicker.Root>
  <EmojiPicker.List />
</EmojiPicker.Root>
```

List requires Viewport.

A Viewport without a List renders no grid (development warns).

List must be inside Viewport (ideally its direct child; wrappers from styling libraries are fine), optionally accompanied by `Empty` and `Loading`. A second List is rejected.

There is no child-ordering rule. Root renders whatever you give it, in the order you gave it. Registered parts must remain inside their Root DOM boundary.

## 10a. Empty state

```tsx
<EmojiPicker.Viewport>
  <EmojiPicker.List />
  <EmojiPicker.Empty>
    {({ search }) => <p>No emoji for “{search}”</p>}
  </EmojiPicker.Empty>
</EmojiPicker.Viewport>
```

Renders only while an applied search shows no emojis (counting exactly what the list shows). Without children it renders `labels.searchResultsNone`. The default picker includes it.

## 10b. Skin tone anywhere

```tsx
<EmojiPicker.Root>
  <EmojiPicker.Search />
  <EmojiPicker.Viewport>
    <EmojiPicker.List />
  </EmojiPicker.Viewport>
  <footer>
    <EmojiPicker.SkinTone orientation="vertical" />
  </footer>
</EmojiPicker.Root>
```

`SkinTone` is the managed control (keyboard, focus region, callbacks). Only one skin tone control may exist per Root. Search and Preview never insert one automatically; render it wherever your layout needs it. To build a control from scratch instead, use `useSkinTone()`.

## 10b2. Vertical category rail

```tsx
<EmojiPicker.CategoryNav orientation="vertical" />
```

Stacks the tabs and switches keyboard navigation to Up/Down between tabs (Left/Right leave the rail), announced through `aria-orientation`. `SkinTone` takes the same `orientation` prop for its fan.

## 10c. Hooks

```tsx
function MyPreview() {
  const emoji = EmojiPicker.useActiveEmoji();
  return <div className="my-preview">{emoji ? `${emoji.emoji} ${emoji.names[0]}` : 'Pick one'}</div>;
}

function MyStatus() {
  const { search, resultCount } = EmojiPicker.useSearchState();
  return search ? <span>{resultCount} matches</span> : null;
}
```

Hooks throw in development when called outside `Root`.

## 11. Styling

```tsx
<EmojiPicker.Root className="picker">
  <EmojiPicker.Search className="search" />
  <EmojiPicker.Viewport className="viewport">
    <EmojiPicker.List className="list" />
  </EmojiPicker.Viewport>
</EmojiPicker.Root>
```

Managed descendants and the internal panel expose the deliberately small stable part API described in [PRIMITIVES.md](./PRIMITIVES.md#parts-and-replacements).

Styling is opt-in in both directions:

- **Primitives are unbranded by default.** Root always applies the geometry tokens (sizes, spacing, stacking), so a bare composition is fully functional; colors are yours. `<Root colorScheme="light" | "dark" | "auto">` opts into the default color tokens (CSS variables only — no border, background or font on Root).
- **`colorScheme`, not `theme`.** Emotion, styled-components and MUI reserve a `theme` prop on the components they wrap, so `styled(Root)` / `styled(EmojiPicker)` would swallow it. The default picker accepts both (`colorScheme` wins); Root only takes `colorScheme`.
- **The default picker is branded by default.** `<EmojiPicker unstyled />` keeps the batteries-included composition and behavior but drops the chrome and colors, for styling from scratch with `className`, `--epr-*` variables and `[data-epr-part]` selectors.

## 11a. Columns

```tsx
<EmojiPicker columns={8} />
```

`columns` sets the emojis per row on EmojiPicker and Root. The picker's width then fits those columns plus a stable scrollbar gutter, unless the consumer sets a width (`width`, `style` or any class). A container narrower than the columns renders fewer columns instead of clipping. Without `columns`, the width decides the column count, as in v4.

## 12. Data API

The data entry point is defined in [DATA_API.md](./DATA_API.md):

```ts
import {
  getEmojiByUnified,
  searchEmojis,
  type EmojiInfo,
} from 'emoji-picker-react/data';
```

The existing top-level `emojiByUnified` export remains unchanged and is **not** replaced by `getEmojiByUnified`.

`searchEmojis` is dataset search, not "the exact results currently visible in one picker instance." Picker-only filters such as `emojiVersion`, `hiddenEmojis`, and `customEmojis` remain Root configuration.

Each record carries the ready-to-insert `emoji` text and a display `name`. v5 does not promise Slack-shortcode conversion because the dataset does not establish canonical Slack alias semantics.

## 12a. Dataset loading and bundle size

`emojiData` accepts an object (synchronous, SSR-safe) or a loader:

```tsx
const loadFrench = () => import('emoji-picker-react/data/emojis-fr');

<EmojiPicker emojiData={loadFrench} />
```

- The default `emoji-picker-react` entry bundles the English dataset and is always synchronous.
- The `emoji-picker-react/primitives` entry does **not** load the dataset up front. A Root without `emojiData` loads the bundled English dataset on demand (its own chunk in ESM builds; the configured minimal consumer currently measures about 33 KiB min+gz up front including ShipStyles), rendering `<Loading>` meanwhile. Pass an object for server rendering.
- ESM entries share their implementation chunks, so using the default picker and primitives together ships the implementation once.

Hoist loaders (module scope or `useCallback`): a new function identity loads again. Loaders receive `{ signal?: AbortSignal }`; source changes, retries and unmount abort the previous attempt. Zero-argument import loaders remain valid. Rejection and synchronous throws become recoverable state, not an empty successful result. The default picker displays localized error/retry UI. Primitive consumers compose `<LoadError />` next to List/Loading or read `useEmojiDataState()` (`{ loading, error, retry }`). A custom `LoadError` child can be a function receiving `{ error, retry }`.

Import runtime `Categories`, `EmojiStyle`, `SkinTones`, `SkinTonePickerLocation`, `SuggestionMode`, and `Theme` from `/primitives` in a lean composition. Importing runtime values from the main or `/data` entry registers its eager default dataset.

## 12b. Exported types

Both the main and the primitives entry export the types a typed consumer needs without reaching into the package: `PickerProps` / `RootProps`, `EmojiClickData`, `EmojiClickHandler` and `OnEmojiClickApi` (the `onEmojiClick` / `onReactionClick` signature and its `collapseToReactions` API), `SkinToneChangeHandler`, `PickerLabels`, `PreviewConfig`, `CustomEmoji`, `CategoryConfig`, `CategoryIcons`, `EmojiData`, `EmojiDataLoader` / `EmojiDataLoaderOptions` / `EmojiDataInput`, `PickerComponents` with `EmojiRenderProps`, `CategoryHeaderRenderProps`, `CategoryButtonRenderProps`, `SkinToneButtonRenderProps` and `ListEmoji`, plus the literal unions `ThemeValue`, `EmojiStyleValue`, `SuggestionModeValue` and `SkinTonesValue`. `defaultSkinTone` and `skinTone` accept `SkinTonesValue` (`'neutral'`, `'1f3fb'`, … or the `SkinTones` enum). The main entry exports PickerProps (with Props as its alias); the primitives entry exports RootProps and each part’s prop types. See the entry files for their complete exports.

## 13. Locale imports

v4's documentation used:

```ts
import es from 'emoji-picker-react/dist/data/emojis-es';
```

v5 canonicalizes:

```ts
import es from 'emoji-picker-react/data/emojis-es';
```

The documented v4 `dist/data/emojis-*` paths, and the raw `src/data/*.json` datasets, remain working in v5 through deprecated compatibility export aliases. Arbitrary undocumented deep imports do not receive that guarantee.

## 13a. React Server Components

The main and primitives entry files are marked `"use client"`, so a Server Component may render `<EmojiPicker />` directly. `emoji-picker-react/data` is not marked and stays callable on the server.

## 14. Error ownership

The default `<EmojiPicker />` keeps the current library ErrorBoundary.

The primitives Root does not install one. Render/lifecycle errors from consumer UI propagate to the application's surrounding ErrorBoundary when one exists. Event-handler exceptions are not caught by React ErrorBoundaries and follow normal React/browser event behavior.

## 15. Development validation

The validation model is intentionally narrow:

- render/context checks catch primitive-outside-Root (and hooks called outside Root), List-outside-Viewport, and invalid Viewport children (mode is driven by Root props and public usePickerMode actions; caller JSX controls Panel/Reactions placement);
- singleton duplicates are detected by Root registration after mount;
- development throws on a second singleton registration;
- production keeps the first registration authoritative and warns once;
- there is no "missing Viewport after paint" validator because Viewport/List are optional;
- SSR performs only render-time/context validation.

Exact error text is not semver API.

## Native search, panel styling and active custom cells

`SearchInput` forwards its ref and native input props directly to an input. Root owns `searchValue`, `defaultSearchValue` and `onSearchChange`; input `onChange` is an observer. Supply `as={Input}` for a design-system component that forwards its ref and native input props to one real input. Placeholder, autofocus and accessible label can be supplied directly. Use either Search or SearchInput per Root; they share IME handling, region registration and results announcements.

Panel accepts className, style, native attributes and handlers directly. Panel owns its hidden/inert presence; its children and layout come from the caller’s JSX. Apply flex/grid/gap classes on Panel itself.

Custom `EmojiRenderProps.emoji.isActive` and `data-epr-active` indicate hover or keyboard focus. Only the previous and next active cells are notified; unrelated cells do not rerender for each hover. Preserve all managed button props and position styles when replacing markup.

## Lifetimes, ownership and design-library inputs

Root owns its callback scope even when Roots are nested. The default wrapper may supply fresh callbacks across its memo boundary only to its own Root. Conditionally unmount Root to remove its content and abort pending loading; mounting it again starts a new lifetime. The assembled EmojiPicker retains its `open` prop: closed, it renders nothing but keeps its state, as in v4. Native disabled/read-only search inputs do not accept grid type-to-search proposals.

Managed markup cannot be replaced through `dangerouslySetInnerHTML`; structural children, roles and reserved picker attributes remain owned by the library. Stable forwarded refs are retained across unrelated renders, and callback-ref cleanup is supported while retaining the React 16.8 runtime floor. Malformed async loader output enters the same localized error/retry path as a rejected load.

SearchInput infers design-library props from its `as` component, including required options, while protecting the Root-owned value and native input contract. Custom List cells and headers receive structural styles without managed decorative appearance. They own their visible focus and design-library styling. Grid row measurement uses the outer border box, so design-library borders do not shrink virtualized row spacing.

## Checked usage examples

The `tsx check` blocks in this reference are compiled from the Markdown itself by `npm run check:contracts`. They use the current source API, including JSX-owned presence and placement.

### Default picker and exported types

```tsx check
import * as React from 'react';
import EmojiPicker, {
  type EmojiClickHandler, type EmojiDataLoader, type PickerLabels,
} from 'emoji-picker-react';

const labels: Partial<PickerLabels> = { searchPlaceholder: 'Rechercher' };
const loadFrench: EmojiDataLoader = () => import('emoji-picker-react/data/emojis-fr');
const onPick: EmojiClickHandler = (data, _event, api) => {
  data.getImageUrl('apple');
  api?.collapseToReactions();
};

export function LocalizedPicker() {
  const [search, setSearch] = React.useState('');
  return <EmojiPicker emojiData={loadFrench} labels={labels}
    searchValue={search} onSearchChange={setSearch} onEmojiClick={onPick}
    colorScheme="dark" unstyled />;
}
```

### Design-system input and replacement cell

```tsx check
import * as React from 'react';
import * as Picker from 'emoji-picker-react/primitives';

const Field = React.forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => <input {...props} ref={ref} />,
);
function Cell({ emoji, ...props }: Picker.EmojiRenderProps) {
  return <button {...props} data-active={emoji.isActive} />;
}

export function CustomPicker() {
  return <Picker.Root components={{ Emoji: Cell }} style={{ height: 450 }}>
    <Picker.SearchInput as={Field} aria-label="Find emoji" />
    <Picker.SkinTone orientation="vertical" />
    <Picker.Viewport><Picker.List /><Picker.Empty /></Picker.Viewport>
  </Picker.Root>;
}
```

### External search and mode actions

```tsx check
import * as React from 'react';
import * as Picker from 'emoji-picker-react/primitives';

function Actions() {
  const { search, resultCount } = Picker.useSearchState();
  const { setValue, clear } = Picker.useSearchActions();
  const { expand, collapse, canExpand } = Picker.usePickerMode();
  const { categories, jumpToCategory } = Picker.useCategoryNavigation();
  return <div>
    <input value={search} onChange={event => setValue(event.target.value)} />
    <button onClick={clear}>Clear</button>
    <button disabled={!canExpand} onClick={expand}>Expand</button>
    <button onClick={collapse}>Collapse</button>
    {categories.map(category => <button key={category.id}
      onClick={() => jumpToCategory(category.id)}>{category.name}</button>)}
    <output>{resultCount}</output>
  </div>;
}

export function ExternalSearchPicker() {
  return <Picker.Root>
    <Actions /><Picker.Reactions />
    <Picker.Panel><Picker.Viewport><Picker.List /></Picker.Viewport></Picker.Panel>
  </Picker.Root>;
}
```

### Framework-free data entry

```tsx check
import { getEmojiByUnified, searchEmojis, type EmojiInfo } from 'emoji-picker-react/data';
import es from 'emoji-picker-react/data/emojis-es';

export const results: readonly EmojiInfo[] = searchEmojis('gato', { emojiData: es });
export const first = getEmojiByUnified(results[0]?.unified ?? '1f431', { emojiData: es });
export const label = first ? `${first.emoji} ${first.name}` : '';
```

### Default picker root attributes

`EmojiPicker` accepts `id`, `title`, `lang`, `dir`, `aria-*` and `data-*` identifying
attributes on its root, alongside `className` and `style`. Its public types include
the named attributes and React ARIA attributes. The library reserves `role` and
`data-epr-*`; use a wrapper or primitives for other native event handlers.

<!-- source: docs/v5/PRIMITIVES.md -->

<!-- Primitives -->

# Picker primitives

`emoji-picker-react/primitives` exposes the same engine used by the default
`EmojiPicker`. It lets you arrange managed controls and supply your own layout
and appearance without duplicating filtering, virtualization or selection.

## Composition owns presence and placement

`Root` renders the actual `aside` and exactly the children you supply. It never
inserts a `Panel`, `Reactions`, search input, preview or skin-tone control.
There is no managed/explicit composition switch.

```tsx check
import * as React from 'react';
import {
  Root, Panel, Reactions, Search, SkinTone, CategoryNav,
  Viewport, List, Preview, Empty, Loading, LoadError,
  type EmojiClickData,
} from 'emoji-picker-react/primitives';

export function ComposedPicker({
  onSelect,
}: {
  onSelect: (emoji: EmojiClickData) => void;
}) {
  return (
    <Root
      appearance="default"
      reactionsDefaultOpen
      style={{ width: 350, height: 450 }}
      onEmojiClick={onSelect}
    >
      <Reactions />
      <Panel className="my-picker">
        <Search><SkinTone /></Search>
        <CategoryNav />
        <Viewport>
          <List />
          <Empty />
          <Loading />
          <LoadError />
        </Viewport>
        <Preview />
        <footer>Choose an emoji</footer>
      </Panel>
    </Root>
  );
}
```

- Omit `Search`/`SearchInput` to omit the built-in search UI. Type-to-search
  leaves keystrokes alone when no input is mounted.
- Omit `Preview` or `SkinTone` to omit those controls. Mounting them always
  enables their UI; `Search` and `Preview` never insert a tone control.
- Place `SkinTone` as a trailing child of `Search` or `Preview`, or anywhere
  inside Root. Its orientation is `horizontal` by default; use `vertical`
  for a footer control.
- Conditional rendering of Root itself controls whether the picker exists.
- `Panel` is optional for a full-picker-only composition. When using compact
  reactions mode, supply `Reactions` outside `Panel` and put expanded content
  inside `Panel`. Panel manages hidden/inert state when reactions are open.
- Root preserves its supplied dimensions during mode changes. The consumer
  owns compact layout; the default picker supplies its own compact styling.
- Wrappers and ordinary consumer controls are supported. `List` must be inside
  `Viewport`; `Empty`, `Loading` and `LoadError` are normally its siblings.
- Only one of each managed region is supported per Root. Search and SearchInput
  share a single input region. Duplicate parts fail in development.
- Portaling an entire Root is supported. Registered parts must stay inside
  their Root DOM boundary.

## Root configuration

Root accepts engine settings such as `emojiData`, `categories`, `customEmojis`,
`hiddenEmojis`, `emojiStyle`, `getEmojiUrl`, `columns`, `skinTone`,
`defaultSkinTone`, `reactions`, `reactionsDefaultOpen`, `allowExpandReactions`,
`searchValue`, `defaultSearchValue`, `suggestedEmojis`, `suggestedEmojisMode`,
`labels`, `nonce`, `cssLayer` and the picker callbacks.

Presence/placement options from the default picker are **not Root props**:
`open`, `searchDisabled`, `skinTonesDisabled`, `skinTonePickerLocation`, and
`previewConfig.showPreview`. Removed convenience options `composition` and
`panelProps` are also unsupported; put those attributes on an actual Panel.
JavaScript callers receive a development warning for these ignored switches;
they never hide a mounted part or reach the DOM.

`previewConfig` retains `defaultEmoji` and `defaultCaption`. Root supports native
`className`, `style`, identifying attributes and event handlers. Use native
style/class sizing; `width`, `height`, `theme` and `unstyled` are default-picker
appearance props. Root's `colorScheme` supplies light/dark/auto color tokens;
`appearance="default"` opts into built-in leaf appearance. Bare compositions
have no branded default appearance. Give Root a bounded height for scrolling.

The library owns `role` and `data-epr-*` on managed elements. These consumer
attributes are filtered. Ref forwarding points to the part's native element.

## Parts and replacements

`Search` includes the input, result announcement and clear control.
`SearchInput` exposes the same managed input without the surrounding chrome;
`as={DesignInput}` accepts a ref-forwarding input adapter. Root owns its value
and change/composition handling. Native `disabled` and `readOnly` input props
remain meaningful interaction settings, not component-presence switches.

`CategoryNav` exposes horizontal or vertical tab orientation. `Viewport` owns
scrolling and variations; `List` owns the managed grid. `Preview` shows hovered
or focused emoji state. `SkinTone` uses the shared tone selection engine.
Inside `Search`, a horizontal `SkinTone` reserves space for its expanded fan;
the input shrinks as the fan opens and regains that space when it closes.
`Reactions` renders the compact list only while reactions mode is active.
`Empty`, `Loading` and `LoadError` render according to search/data state and
accept custom content; LoadError's render function receives `error` and `retry`.

`Root components` supplies shared emoji/category/tone/control replacements.
`List components` overrides grid emoji cells and category headers. Keep each
managed native target, ref, geometry and behavioral attributes intact. Use
stable component identities and provide visible keyboard focus styling.

## State and actions

All public hooks require Root:

- `useActiveEmoji()` returns hovered/focused emoji selection data or null,
  including when no Preview is mounted.
- `useSkinTone()` returns the active tone and its setter. With controlled
  `skinTone`, the setter proposes through `onSkinToneChange`.
- `useSearchState()` returns accepted raw `search` and the applied/debounced
  `resultCount`. Controlled edits emit proposals; only accepted `searchValue`
  changes filtering. Parent-driven updates do not re-emit.
- `useSearchActions()` returns `setValue(raw)` and `clear()`. They work without
  SearchInput, allowing external or custom controls. Clear focuses a mounted
  input when available.
- `useEmojiDataState()` returns `loading`, recoverable `error` and `retry()`.
  An object dataset works synchronously; a stable loader is loaded on demand.
- `useCategoryNavigation()` returns category IDs/names, `activeCategory` and
  `jumpToCategory(id)`. Use the returned IDs, including custom group identities.
  Group order/membership changes cancel pending navigation completions.
- `usePickerMode()` returns `reactionsOpen`, `canExpand`, `expand()` and
  `collapse()`. Expansion respects `allowExpandReactions`. Supply Reactions
  and Panel if your composition uses collapse.

Omitting search UI does not disable filtering: a controlled searchValue or
custom action can still filter the list. Likewise, omitting SkinTone does not
remove emoji variants or prevent controlled/programmatic tone selection.
These are engine behaviors, distinct from the existence of their controls.

## Default-picker compatibility

The default `EmojiPicker` is assembled from these exported parts. It keeps its
legacy visibility/placement props and translates them into conditional JSX.
Its tone-location fallback still moves the control between Search and Preview
when one is hidden. `skinTonesDisabled` also preserves its legacy suppression
of grid variation affordances. These compatibility rules belong to the
assembled picker and do not add secondary visibility switches to primitives.

<!-- source: docs/v5/STYLING.md -->

<!-- Styling -->

# Styling

Choose batteries included or BYOD (bring your own design, design language and design library): every mode below keeps the same behavior, accessibility and virtualization, and only changes who owns the appearance.

## 1. Two styling modes

### Default picker

`<EmojiPicker />` uses the official appearance and remains visually compatible with v4.

It continues to support the documented v4 CSS custom properties.

`<EmojiPicker unstyled />` keeps the supplied composition and behavior while removing decorative appearance from every managed part: control colors/resets, rounding, typography, shadows, blur, motion and decorative icons. Browser native appearance remains. Geometry, positioning, scrolling and presence stay managed. A bare Root behaves the same. Color variables have no effect in these modes because no rule reads them; size variables still apply. `Root appearance="default"` explicitly opts into built-in leaf appearance for token-based re-skins and paints Root with `var(--epr-bg-color)` at zero specificity (no border, radius or shadow). `colorScheme` supplies variables only.

### Structural primitives

`emoji-picker-react/primitives` exposes the same behavioral renderer, unbranded by default:

- every Root applies the geometry tokens (sizes, spacing, stacking) and a zero-specificity `box-sizing: border-box` fallback, so a bare composition lays out and measures correctly with no appearance tokens; design-library classes retain their own box sizing (for example MUI's content-box inputs);
- `<Root colorScheme="light" | "dark" | "auto">` defines the default color tokens (variables only). They take effect with `appearance="default"` or in your own CSS (`background: var(--epr-bg-color)`);
- token presets are exported as data: `structuralPickerTokens`, `lightPickerTokens`, `darkPickerTokens`, `defaultPickerTokens`.

With `List components`, custom emoji buttons receive geometry and behavior attributes without the default button reset, rounding, hover/focus colors or variation indicator decoration. Custom category headers receive sticky positioning and measurement without default background, blur, font styling or text transformation. Supply your own decoration and visible focus. Native `SearchInput` and its design-library `as` component receive no managed search appearance.

Headless composition uses this managed rendering contract; consumers retain the documented geometry while choosing their design components.

## 2. Structural CSS

The library guarantees correct behavior only while these structural responsibilities remain intact:

| Part | Reserved structural responsibility |
| --- | --- |
| `root` | picker-instance containing block where required by overlays |
| `panel` | expanded-region presence/layout used by picker mode transitions |
| `viewport` | vertical scroll container, horizontal clipping and measurement boundary |
| `list` | logical/virtualized grid container |
| `category` | category positioning/measurement boundary |
| `category-content` | grid layout and measured category height |
| `emoji` | measured cell geometry used by logical row/column calculations |
| `variation-picker` | overlay positioning that must not corrupt grid measurement |

The current implementation reserves these declarations:

- Root: `position: relative`, column flex layout, clipping; panel: flexible column with `min-height: 0` and hidden/inert presence controlled by Root.
- Viewport: relative flex child with `overflow-y: scroll` and horizontal clipping.
- List: zero list margin/padding; category content: relative grid using `--epr-emoji-fullsize` columns and `--epr-category-padding`.
- `columns` layouts: only the grid sets Root's width. Search, a horizontal CategoryNav and Preview use inline-size containment and fill the row the grid establishes, so hover/focus titles and an opening skin tone fan never resize the picker or change its column count. A vertical CategoryNav rail still adds its own width beside the grid.
- Cells: measured width/height/max dimensions from `--epr-emoji-fullsize`; the supplied inline absolute position and offsets place virtualized cells.
- Category labels: sticky top position, `--epr-category-label-height`, documented padding and stacking tokens.

Change supported size tokens to alter dimensions; preserve the supplied position styles when wrapping design-library buttons.

Not every value of `display`, `position`, `overflow`, row height or containment is safe to override. For example, forcing `overflow: visible` on Viewport or `display: contents` on a measured grid container breaks keyboard navigation and virtualization. Dimensions that affect layout are either measured from the DOM or exposed as the size tokens above, and the variation menu positions itself inside the Viewport, so you never need to change its overflow.

## 3. Appearance CSS

Consumers may customize appearance through:
- `className`;
- `style`;
- existing documented `--epr-*` variables;
- a deliberately small set of stable `data-epr-part` selectors.

Appearance includes, where it does not invalidate structural assumptions:
- color;
- background;
- border;
- border radius;
- typography;
- decorative shadows;
- icon color;
- hover/focus colors;
- spacing tokens explicitly documented as safe.

## 4. v4 CSS variable inventory

The following variables are already documented public customization surface and remain supported in v5 unless separately deprecated:

### General
- `--epr-emoji-size`
- `--epr-emoji-padding`
- `--epr-bg-color`
- `--epr-text-color`
- `--epr-picker-border-color`
- `--epr-picker-border-radius`
- `--epr-horizontal-padding`
- `--epr-highlight-color`
- `--epr-hover-bg-color`
- `--epr-focus-bg-color`

### Search
- `--epr-search-input-bg-color`
- `--epr-search-input-bg-color-active`
- `--epr-search-input-text-color`
- `--epr-search-input-placeholder-color`
- `--epr-search-border-color`
- `--epr-search-border-color-active`
- `--epr-search-input-border-radius`
- `--epr-search-input-height`
- `--epr-search-icon-color`

### Category navigation
- `--epr-category-navigation-button-size`
- `--epr-category-icon-active-color`
- `--epr-category-icon-inactive-color`

### Category labels
- `--epr-category-label-bg-color`
- `--epr-category-label-text-color`
- `--epr-category-label-height`

### Preview
- `--epr-preview-height`
- `--epr-preview-emoji-size` (v5; default `45px`)
- `--epr-preview-text-size`
- `--epr-preview-text-color`

### Native emoji font
- `--epr-emoji-font-family` (v5) — font stack for native emojis, e.g. a country-flag polyfill font; native support detection measures this same font.

### Skin tone
- `--epr-skin-tone-picker-menu-color`
- `--epr-skin-tone-size`

### Dark mode
- `--epr-dark-bg-color`
- `--epr-dark-picker-border-color`
- `--epr-dark-text-color`
- `--epr-dark-search-input-bg-color`
- `--epr-dark-hover-bg-color`

The already-deprecated `--epr-emoji-gap` remains deprecated; do not revive it as a v5 design token.

## 5. Stable part selectors

Expose only parts needed for supported product styling.

Initial required part API:

- `root`
- `panel`
- `reactions`
- `reaction`
- `expand-reactions`
- `search`
- `search-input` (the native input, whether rendered by `Search`, `SearchInput` or a design-library `as` component)
- `search-clear`
- `skin-tone`
- `skin-tone-button`
- `category-nav`
- `category-tab`
- `viewport`
- `list`
- `category`
- `category-label`
- `category-content`
- `emoji`
- `variation-picker`
- `preview`
- `empty` (v5, the `Empty` primitive)
- `loading` (v5, the `Loading` primitive)
- `load-error` (v5, the `LoadError` primitive)

Part names are public API: renaming or removing one is a breaking change.

A part is not automatically a composition primitive. `category-content` and `variation-picker` are internal managed structures with stable styling hooks. Panel and Reactions are exported primitives with those same-named part selectors; see [PRIMITIVES.md](./PRIMITIVES.md#parts-and-replacements).

### Library data attributes

Beyond `data-epr-part`, the library emits a small set of value-carrying data attributes. All of them live in the reserved `data-epr-*` namespace so they can never collide with consumer `data-*` props:

| Attribute | On | Value |
| --- | --- | --- |
| `data-epr-unified` | `[data-epr-part="emoji"]` | lowercase unified code actually rendered, including skin-tone variation |
| `data-epr-category` | `[data-epr-part="category"]` | category id, or the custom group name |
| `data-epr-emojis-per-row` | `[data-epr-part="category-content"]` | measured column count |
| `data-epr-direction` | `[data-epr-part="skin-tone"]` | fan axis (`horizontal` / `vertical`) |

State is exposed through ARIA where ARIA has a word for it: the active category tab is `[data-epr-part="category-tab"][aria-selected="true"]`, a vertical tab bar is `[role="tablist"][aria-orientation="vertical"]`.

These replace v4's undocumented `data-unified`, `data-name` and `data-emojis-per-row`. Like part names, they are public API.

## 6. Emoji item boundary

Emoji cells and category headers can be replaced through `List components={{ Emoji, CategoryHeader }}` (see [API.md](./API.md#9-custom-emoji-cells-and-category-headers)). The library keeps owning their behavior: each component receives the library-owned props (type, role, class, position style, tabIndex, aria-label, `data-epr-*`) and must spread them onto its element. Ordering, virtualization and grid semantics stay library-owned; there is no render prop over the whole list.

### Hiding category titles

Hide titles with `[data-epr-part="category-label"] { display: none }` and set `--epr-category-label-height: 0px`. A hidden title measures 0, so virtualization offsets stay correct.

## 7. Specificity and cascade

Library CSS is unlayered by default, and token declarations are wrapped in `:where()` (zero specificity):

- any consumer selector that sets an `--epr-*` token — plain CSS, CSS Modules, Emotion, styled-components, MUI `styled`/`sx`, Tailwind arbitrary properties — wins regardless of load order;
- because the structural rules are unlayered, global application resets (`* { margin: 0; padding: 0 }`, `button { all: unset }`, …) cannot break the picker's layout — unlayered rules beat any layered reset, and the picker's selectors out-specify bare element resets;
- part overrides (`[data-epr-part="…"]` under your root class) win by ordinary specificity;
- layered frameworks can opt the picker into a layer with `cssLayer="epr"` and declare it first, e.g. Tailwind v4: `@layer epr, theme, base, components, utilities;` before importing Tailwind, so utilities override it. In that mode an unlayered global reset in the app would also override the picker, so keep resets in Tailwind's `base` layer;
- under jsdom, which ignores `@layer` rules, the CSS is always emitted unlayered so test environments keep computed styles.

Rules:

- structural correctness must not depend on Tailwind/CSS Modules being loaded in a particular order;
- cosmetic consumer overrides should win through ordinary cascade without requiring `!important`;
- broad `!important` usage is not needed for cosmetic overrides.

## 8. Structural failures

CSS that breaks the structural rules in section 2 voids the virtualization and keyboard navigation guarantees. Change size tokens or `columns` instead.

<!-- source: docs/v5/STYLING_RECIPES.md -->

<!-- Styling recipes by library -->

# Styling recipes by library

Copyable starting points for every styling stack, for each of the three ways to use the picker. Every snippet targets the same public surface: `className` / `style`, the `--epr-*` variables and the stable `[data-epr-part]` selectors. Nothing here overrides structural layout (viewport overflow, grid geometry, cell positions), so keyboard navigation and virtualization keep working.

**One rule decides what a snippet can do.** Color variables (`--epr-bg-color`, `--epr-highlight-color`, …) theme the *built-in look*. `unstyled` and a bare primitives `Root` remove the built-in look, so color variables do nothing there and you style the parts directly. Size variables (`--epr-emoji-size`, paddings, heights) apply in every mode. `Root appearance="default"` brings the built-in look into a composition.

| Path | Component | You write |
| --- | --- | --- |
| **Theme** the built-in look | `<EmojiPicker className="…" />` | variables on one class, optional part tweaks |
| **Unstyled** supplied layout | `<EmojiPicker unstyled className="…" />` | a stylesheet for every part |
| **Composed** layout | `emoji-picker-react/primitives` | layout, parts and (optionally) your own components |

Parts you can target: `root`, `panel`, `search`, `search-input`, `search-clear`, `skin-tone`, `skin-tone-button`, `category-nav`, `category-tab`, `viewport`, `list`, `category`, `category-label`, `category-content`, `emoji`, `variation-picker`, `preview`, `empty`, `loading`, `load-error`, `reactions`, `reaction`. State: `[data-epr-active]` on the hovered or focused emoji, active tab and active tone; `[aria-selected="true"]` on the current tab; `[aria-pressed="true"]` on the current tone.

Two surfaces are transparent under `unstyled` or a bare Root until you give them a background: the sticky `category-label` and the `variation-picker` overlay. Always keep a visible `:focus-visible` style on buttons and the input.

Every stack below has a runnable version in [`stories/integrations`](../../stories/integrations) and, per design, in [`stories/recipes`](../../stories/recipes) (25 designs × 7 stacks, screenshot- and axe-tested). The [`example/`](../../example) app shows the three paths in plain CSS.

---

## Plain CSS

### Theme

```css
.brand-picker {
  --epr-bg-color: #faf5ff;
  --epr-category-label-bg-color: #faf5ffe6;
  --epr-search-input-bg-color: #f3e8ff;
  --epr-picker-border-color: #e9d5ff;
  --epr-text-color: #6b21a8;
  --epr-highlight-color: #7c3aed;
  --epr-hover-bg-color: #ede9fe;
  --epr-focus-bg-color: #ddd6fe;
  --epr-picker-border-radius: 16px;
  --epr-emoji-size: 26px;
}
.brand-picker [data-epr-part='category-label'] {
  font-size: 12px;
  letter-spacing: 0.08em;
  text-transform: uppercase;
}
```

```jsx
<EmojiPicker colorScheme="auto" className="brand-picker" />
```

Variables are declared by the library at zero specificity, so one class wins in any load order; no `!important`, no `aside.EmojiPickerReact` selectors.

### Unstyled

```css
.paper-picker {
  --epr-emoji-size: 28px;
  background: Canvas;
  color: CanvasText;
  border: 1px solid #8884;
  border-radius: 14px;
  font: 14px/1.4 system-ui, sans-serif;
}
.paper-picker [data-epr-part='search'] { padding: 12px 12px 8px; }
.paper-picker [data-epr-part='search-input'] {
  padding-inline: 12px 36px;
  border: 1px solid #8886;
  border-radius: 10px;
  background: transparent;
  color: inherit;
  font: inherit;
}
.paper-picker :is([data-epr-part='emoji'], [data-epr-part='category-tab'],
    [data-epr-part='search-clear'], [data-epr-part='skin-tone-button']) {
  border: 0;
  border-radius: 8px;
  background: transparent;
  color: inherit;
  cursor: pointer;
}
.paper-picker [data-epr-part='category-tab'] { color: #8888; }
.paper-picker [data-epr-part='category-tab'][aria-selected='true'] { color: #2563eb; }
.paper-picker [data-epr-part='emoji'][data-epr-active] { background: #8882; }
.paper-picker :is(button, input):focus-visible { outline: 2px solid #2563eb; outline-offset: -2px; }
.paper-picker [data-epr-part='category-label'] {
  background: Canvas;
  color: #888;
  font-size: 11px;
  font-weight: 600;
  text-transform: uppercase;
}
.paper-picker [data-epr-part='variation-picker'] {
  background: Canvas;
  border: 1px solid #8884;
  border-radius: 10px;
  box-shadow: 0 4px 12px #0003;
}
```

```jsx
<EmojiPicker unstyled className="paper-picker" />
```

### Composed

```jsx
import * as Picker from 'emoji-picker-react/primitives';

<Picker.Root className="card" columns={8} onEmojiClick={(e) => insert(e.emoji)}>
  <Picker.Search />
  <Picker.CategoryNav className="tabs" />
  <Picker.Viewport>
    <Picker.List />
    <Picker.Empty className="notice" />
    <Picker.Loading className="notice" />
    <Picker.LoadError className="notice" />
  </Picker.Viewport>
  <Picker.Preview />
</Picker.Root>
```

```css
.card { height: 440px; background: #0b1220; color: #e2e8f0; border-radius: 16px; }
.card [data-epr-part='panel'] { gap: 8px; }
.tabs { border-bottom: 1px solid #1e293b; padding: 0 12px; }
/* …then the same part rules as the unstyled sheet above. */
```

A bare Root has no height: give it one so the viewport scrolls and virtualizes. Render Panel and put flex/gap classes or styles on it directly; `[data-epr-part='panel']` is its stable selector.

---

## CSS Modules

Module classes land on the root; the parts are global attribute selectors, so wrap them in `:global()`.

```css
/* picker.module.css */
.picker {
  --epr-highlight-color: #0f766e;
  --epr-hover-bg-color: #ccfbf1;
  border-radius: 14px;
}
.picker :global([data-epr-part='category-label']) {
  font-weight: 600;
  text-transform: none;
}
.picker :global([data-epr-part='emoji']) {
  border-radius: 6px;
}
```

```jsx
import styles from './picker.module.css';

<EmojiPicker className={styles.picker} />;            // theme
<EmojiPicker unstyled className={styles.picker} />;   // unstyled: add rules for every part
<Picker.Root className={styles.picker}>…</Picker.Root> // composed
```

Parts also take their own module class directly: `<Picker.List className={styles.list} />`, `<Picker.CategoryNav className={styles.nav} />`.

---

## Tailwind CSS (v4)

Tailwind utilities live in cascade layers and cannot beat unlayered CSS, so opt the picker into a layer declared *before* Tailwind's:

```css
/* app.css */
@layer epr, theme, base, components, utilities;
@import 'tailwindcss';
```

Then pass `cssLayer="epr"`; every utility now wins without `!important`.

### Theme

Arbitrary properties set variables; arbitrary variants reach the parts:

```jsx
<EmojiPicker
  cssLayer="epr"
  className="rounded-2xl shadow-xl ring-1 ring-zinc-950/10
    [--epr-bg-color:var(--color-white)] [--epr-text-color:var(--color-zinc-600)]
    [--epr-highlight-color:var(--color-indigo-600)] [--epr-hover-bg-color:var(--color-indigo-50)]
    [--epr-category-label-bg-color:color-mix(in_oklab,var(--color-white)_92%,transparent)]
    [--epr-emoji-size:26px]
    [&_[data-epr-part=emoji]]:rounded-lg
    [&_[data-epr-part=category-label]]:text-xs [&_[data-epr-part=category-label]]:font-semibold [&_[data-epr-part=category-label]]:uppercase"
/>
```

### Unstyled

Add `unstyled` and style the parts with variants instead of variables:

```jsx
<EmojiPicker
  unstyled
  cssLayer="epr"
  className="rounded-2xl border border-zinc-200 bg-white text-zinc-800 shadow-xl
    [&_[data-epr-part=search]]:p-3
    [&_[data-epr-part=search-input]]:h-9 [&_[data-epr-part=search-input]]:rounded-lg [&_[data-epr-part=search-input]]:border [&_[data-epr-part=search-input]]:border-zinc-300 [&_[data-epr-part=search-input]]:bg-transparent [&_[data-epr-part=search-input]]:px-3
    [&_[data-epr-part=category-tab]]:rounded-md [&_[data-epr-part=category-tab]]:text-zinc-400 [&_[data-epr-part=category-tab][aria-selected=true]]:text-indigo-600
    [&_[data-epr-part=category-label]]:bg-white [&_[data-epr-part=category-label]]:text-xs [&_[data-epr-part=category-label]]:font-semibold [&_[data-epr-part=category-label]]:uppercase [&_[data-epr-part=category-label]]:text-zinc-500
    [&_[data-epr-part=emoji]]:rounded-lg [&_[data-epr-part=emoji][data-epr-active]]:bg-indigo-50
    [&_[data-epr-part=variation-picker]]:rounded-lg [&_[data-epr-part=variation-picker]]:border [&_[data-epr-part=variation-picker]]:bg-white [&_[data-epr-part=variation-picker]]:shadow-md
    [&_button:focus-visible]:outline-2 [&_button:focus-visible]:outline-indigo-600 [&_input:focus-visible]:outline-2 [&_input:focus-visible]:outline-indigo-600"
/>
```

### Composed

Utilities go straight onto each part, and `components` lets you write the buttons yourself:

```jsx
import * as Picker from 'emoji-picker-react/primitives';

const components: Picker.PickerComponents = {
  Emoji: ({ emoji, className, ...props }) => (
    <button {...props} className={`${className} rounded-lg hover:bg-zinc-100 focus-visible:ring-2 ${emoji.isActive ? 'bg-zinc-100' : ''}`} />
  ),
  CategoryButton: ({ category, className, ...props }) => (
    <button {...props} className={`${className} rounded-md ${category.isActive ? 'text-indigo-600' : 'text-zinc-400'}`} />
  ),
};

<Picker.Root cssLayer="epr" components={components} className="h-[420px] w-[352px] rounded-2xl bg-white shadow-xl">
  <Picker.Panel className="gap-2">
    <Picker.SearchInput className="mx-3 mt-3 h-9 rounded-lg border border-zinc-300 px-3" />
    <Picker.CategoryNav className="border-b border-zinc-100 px-2" />
    <Picker.Viewport>
      <Picker.List />
      <Picker.Empty className="p-6 text-center text-sm text-zinc-500" />
    </Picker.Viewport>
  </Picker.Panel>
</Picker.Root>;
```

Spread `className` from the managed props: it carries the measured cell geometry.

---

## shadcn/ui

### Theme

Map the picker's variables to shadcn's semantic variables once; light, dark and custom themes then follow automatically:

```css
.emoji-picker {
  --epr-bg-color: var(--popover);
  --epr-category-label-bg-color: var(--popover);
  --epr-text-color: var(--muted-foreground);
  --epr-highlight-color: var(--primary);
  --epr-hover-bg-color: var(--accent);
  --epr-focus-bg-color: var(--accent);
  --epr-picker-border-color: var(--border);
  --epr-search-input-bg-color: transparent;
  --epr-search-border-color: var(--input);
  --epr-search-border-color-active: var(--ring);
  --epr-search-input-text-color: var(--popover-foreground);
}
```

```jsx
<PopoverContent className="w-auto p-0">
  <EmojiPicker cssLayer="epr" className="emoji-picker" onEmojiClick={(e) => insert(e.emoji)} />
</PopoverContent>
```

### Composed: the registry component

[`registry/emoji-picker.tsx`](../../registry/emoji-picker.tsx) is a full shadcn-style component: a bare `Root`, your theme classes (`bg-popover`, `bg-accent`, `border-input`, `text-muted-foreground`), a `components` map for cells, headers, tabs and the tone button, and the `SearchInput` styled like shadcn's `Input`. Install it from the registry item the website publishes (generated into `website/public/r/emoji-picker.json`):

```sh
npx shadcn@latest add https://ealush.com/emoji-picker-react/r/emoji-picker.json
```

Or copy the file into `components/ui/emoji-picker.tsx` and compose it with your `Popover`; the host owns insertion and dismissal, and Escape closes an open variation menu before it reaches the popover.

---

## Emotion

`theme` is reserved by Emotion on components it wraps, so pass `colorScheme`.

### Theme

```jsx
import styled from '@emotion/styled';
import EmojiPicker from 'emoji-picker-react';

const ThemedPicker = styled(EmojiPicker)(({ theme }) => ({
  '--epr-bg-color': theme.colors.surface,
  '--epr-category-label-bg-color': theme.colors.surface,
  '--epr-highlight-color': theme.colors.accent,
  '--epr-hover-bg-color': theme.colors.accentSoft,
  borderRadius: theme.radius,
}));

<ThemedPicker colorScheme="dark" />;
```

### Unstyled

```jsx
const PaperPicker = styled(EmojiPicker)({
  background: '#fff',
  borderRadius: 14,
  "[data-epr-part='search-input']": { border: '1px solid #ddd', borderRadius: 10, padding: '0 12px 0 36px' },
  "[data-epr-part='emoji'], [data-epr-part='category-tab']": { border: 0, borderRadius: 8, background: 'transparent', cursor: 'pointer' },
  "[data-epr-part='emoji'][data-epr-active]": { background: '#eee' },
  "[data-epr-part='category-label']": { background: '#fff', fontSize: 11, fontWeight: 600, textTransform: 'uppercase' },
  "[data-epr-part='variation-picker']": { background: '#fff', border: '1px solid #ddd', borderRadius: 10 },
  'button:focus-visible, input:focus-visible': { outline: '2px solid #2563eb', outlineOffset: -2 },
});

<PaperPicker unstyled />;
```

### Composed

`styled(Picker.Root)` puts the generated class on the real `aside`; the `css` prop works on every part:

```jsx
/** @jsxImportSource @emotion/react */
import { css } from '@emotion/react';
import styled from '@emotion/styled';
import * as Picker from 'emoji-picker-react/primitives';

const Card = styled(Picker.Root)(({ theme }) => ({
  height: 430,
  borderRadius: theme.radius,
  background: theme.colors.surface,
}));

<Card appearance="default" colorScheme="light">
  <Picker.Search />
  <Picker.CategoryNav css={css`border-bottom: 1px dashed #ddd;`} />
  <Picker.Viewport>
    <Picker.List css={css`[data-epr-part='category-label'] { font-style: italic; }`} />
  </Picker.Viewport>
  <Picker.Preview />
</Card>;
```

Leave out `appearance="default"` to own every part's look, as in the unstyled sheet.

---

## styled-components

Same shape as Emotion; `.attrs` is a tidy place for `appearance`.

```jsx
import styled, { ThemeProvider } from 'styled-components';
import * as Picker from 'emoji-picker-react/primitives';

const ThemedPicker = styled(Picker.Root).attrs({ appearance: 'default' })`
  --epr-bg-color: ${(p) => p.theme.panel};
  --epr-text-color: ${(p) => p.theme.text};
  --epr-highlight-color: ${(p) => p.theme.accent};
  --epr-hover-bg-color: ${(p) => p.theme.muted};
  --epr-category-label-bg-color: ${(p) => p.theme.panel}f2;
  border-radius: 18px;
  background: ${(p) => p.theme.panel};

  [data-epr-part='category-label'] {
    font-size: 12px;
    letter-spacing: 0.08em;
    text-transform: uppercase;
  }
`;

<ThemedPicker style={{ width: 340, height: 440 }}>
  <Picker.Search />
  <Picker.CategoryNav />
  <Picker.Viewport>
    <Picker.List />
    <Picker.Empty />
  </Picker.Viewport>
  <Picker.Preview />
</ThemedPicker>;
```

For the default picker, `styled(EmojiPicker)` works the same way (pass `colorScheme`, not `theme`). For a fully custom design drop the `.attrs` and write the part rules yourself.

---

## MUI (Material UI)

### Theme

`styled()` maps the MUI theme onto picker tokens:

```jsx
import { styled } from '@mui/material/styles';
import EmojiPicker from 'emoji-picker-react';

const MuiEmojiPicker = styled(EmojiPicker)(({ theme }) => ({
  '--epr-font-family': theme.typography.fontFamily,
  '--epr-bg-color': theme.palette.background.paper,
  '--epr-text-color': theme.palette.text.secondary,
  '--epr-highlight-color': theme.palette.primary.main,
  '--epr-hover-bg-color': theme.palette.action.hover,
  '--epr-focus-bg-color': theme.palette.action.selected,
  '--epr-search-border-color': theme.palette.divider,
  '--epr-search-input-border-radius': `${theme.shape.borderRadius}px`,
  border: 0,
  '& [data-epr-part="category-label"]': theme.typography.overline,
}));

<Popover open={open} anchorEl={anchor} onClose={close}>
  <MuiEmojiPicker width={340} height={420} onEmojiClick={(e) => insert(e.emoji)} />
</Popover>;
```

### Composed with MUI components

MUI's `TextField` puts its ref on a wrapper, so adapt it: route the ref through `inputRef` and the native props through `slotProps.htmlInput`. MUI buttons need `minWidth: 0` and zero padding to fit the measured cell.

```jsx
import Button from '@mui/material/Button';
import TextField from '@mui/material/TextField';
import Typography from '@mui/material/Typography';
import * as Picker from 'emoji-picker-react/primitives';

const MuiSearchInput = React.forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement> & { variant: 'outlined' | 'filled' }>(
  function MuiSearchInput({ variant, value, onChange, disabled, autoFocus, placeholder, ...native }, ref) {
    return (
      <TextField variant={variant} value={value} onChange={onChange} disabled={disabled} autoFocus={autoFocus}
        placeholder={placeholder} size="small" fullWidth inputRef={ref} slotProps={{ htmlInput: native }} />
    );
  },
);

const components: Picker.PickerComponents = {
  Emoji: ({ emoji, ...props }) => (
    <Button {...props} color="primary" variant="outlined"
      sx={{ minWidth: 0, p: 0, backgroundColor: emoji.isActive ? 'action.selected' : 'transparent', '&:focus-visible': { outline: '2px solid', outlineOffset: -2 } }} />
  ),
  CategoryHeader: ({ category: _c, ...props }) => (
    <Typography {...props} component="div" variant="overline" sx={{ backgroundColor: 'background.paper', color: 'text.secondary' }} />
  ),
  CategoryButton: ({ category, ...props }) => (
    <Button {...props} color="primary" variant={category.isActive ? 'contained' : 'text'} sx={{ minWidth: 0, p: 0 }} />
  ),
};

<Picker.Root colorScheme="light" components={components} style={{ width: 320, height: 400 }}>
  <Picker.Panel style={{ gap: 8 }}>
    <Picker.SearchInput as={MuiSearchInput} variant="outlined" />
    <Picker.CategoryNav />
    <Picker.Viewport>
      <Picker.List />
      <Picker.Empty />
      <Picker.Loading />
      <Picker.LoadError />
    </Picker.Viewport>
  </Picker.Panel>
</Picker.Root>;
```

The complete, browser-tested version is [`stories/v5/MuiComposition.tsx`](../../stories/v5/MuiComposition.tsx).

---

## Checklist for any BYOD design

- **Spread every managed prop** onto one native element in custom components, including `className` and the inline position `style`; remove only the metadata (`emoji`, `category`, `tone`).
- **Give the overlays a surface:** `variation-picker` and the sticky `category-label` are transparent until you style them.
- **Keep focus visible** on cells, tabs, tone buttons, the clear button and the input.
- **Don't touch structure:** viewport overflow, cell width/height, category positioning, `display: contents`. Change `--epr-emoji-size`, `--epr-emoji-padding`, `columns` and the other size variables instead.
- **Give a bare Root a height** (`style`, a class, or `width`/`height` on `EmojiPicker`); otherwise every emoji renders at once and development builds warn.
- **Use `colorScheme`, not `theme`,** on anything wrapped by Emotion, styled-components or MUI `styled()`.
- **Layered CSS:** with Tailwind v4 or any `@layer` setup, pass `cssLayer="epr"` and declare the layer first.

<!-- source: docs/v5/DATA_API.md -->

<!-- Data API -->

# Data API

The v5 data entry point solves issue #430 without replacing the existing top-level `emojiByUnified` export.

## 1. Compatibility

The existing main entry export remains:

```ts
import { emojiByUnified } from 'emoji-picker-react';
```

Its v4 signature/return shape remains source compatible in v5.

The new `emoji-picker-react/data` API is additive and presents a normalized, documented shape rather than making more private compressed dataset fields public.

## 2. Public types

```ts
export type EmojiInfo = Readonly<{
  /** Canonical/base lowercase unified code. */
  unified: string;

  /** The native emoji text for `unified`, ready to insert or render. */
  emoji: string;

  /** Display name: the dataset's full name (the last of `names`). */
  name: string;

  /** Search/display names in dataset order. */
  names: readonly string[];

  /** Lowercase unified codes for supported variations. */
  variations: readonly string[];

  /** Unicode/emoji version from the dataset. */
  addedIn: string;
}>;

export type EmojiDataOptions = Readonly<{
  /**
   * Optional dataset in the same shape accepted by the picker's emojiData prop.
   * Omit for the packaged default English dataset.
   */
  emojiData?: EmojiData;
}>;
```

The `EmojiData` type used by this entry point is exported from `emoji-picker-react/data`.

### Runtime immutability

The readonly TypeScript surface is backed by runtime immutability:

- every prepared `EmojiInfo` record is `Object.freeze`d;
- each record's `names` array is frozen;
- each record's `variations` array is frozen;
- `searchEmojis` returns a fresh frozen result array containing the shared frozen records;
- `getEmojiByUnified` may return a shared frozen record directly;
- caller-provided `emojiData` is never frozen or mutated by the library; normalized prepared records are separate internal objects.

Mutating a returned record or nested array fails (or is a no-op outside strict mode) and never corrupts later lookups or searches.

This protects the shared prepared-data cache from JavaScript consumers mutating a returned record or nested array. Defensive record copies on every lookup are not required and would work against the performance contract.

## 3. Functions

```ts
export function getEmojiByUnified(
  unified: string,
  options?: EmojiDataOptions,
): EmojiInfo | undefined;

export function searchEmojis(
  query: string,
  options?: EmojiDataOptions,
): readonly EmojiInfo[];
```

No other data helpers are part of v5.

### getEmojiByUnified

- trims surrounding whitespace;
- normalizes hexadecimal unified code to lowercase;
- accepts base or variation unified code;
- variation lookup returns the canonical/base EmojiInfo whose `variations` includes the requested variation;
- returns `undefined` for unknown/empty input;
- does not mutate the dataset;
- returns a deeply frozen `EmojiInfo` record when found.

### searchEmojis

- trims and case-folds the query using the same normalization/search index used by picker search;
- empty normalized query returns `[]`;
- preserves stable dataset order among matches;
- returns canonical/base EmojiInfo records;
- when `emojiData` is provided, names/search operate on that dataset;
- returns a fresh frozen result array whose `EmojiInfo` entries are the shared deeply frozen records.

**Important:** `searchEmojis` is dataset search, not a snapshot of one Picker instance's visible results.

It deliberately does not apply Root-specific display layers such as:
- `emojiVersion`;
- `hiddenEmojis`;
- internal `unicodeToHide`;
- `customEmojis`;
- category allowlists/order;
- suggestion-mode state.

Consumers who need exact picker-visible results should use the picker rather than assuming `searchEmojis` reproduces one Root's configured view.

## 4. Shortcodes

v5 does **not** promise `emojiToShortcode` / `shortcodeToEmoji`.

Reason: the current dataset names/aliases do not by themselves establish a contract for Slack's canonical alias choices or `:skin-tone-N:` syntax. Shipping an approximate converter would create a misleading compatibility promise.

The exposed `emoji`, `name`, `names`, `unified` and `variations` data lets consumers build their own mapping.

## 5. Server and bundle use

`emoji-picker-react/data` imports neither React nor ShipStyles, so it runs in Server Components, route handlers and workers, and it shares the picker's own search index and normalization.

Importing it includes (and registers) the default English dataset. The main entry registers it too, while `emoji-picker-react/primitives` loads it on demand unless `emojiData` is supplied. Importing one locale dataset does not pull in the others.

<!-- source: docs/v5/MIGRATION.md -->

<!-- Migrating from v4 -->

# Migrating from v4 to v5

v5 is a strategic architecture release, but it intentionally avoids forcing ordinary consumers to rewrite working configuration.

## Copyable migration prompts

Use the [migration audit prompt](PROMPTS.md#audit-a-v4-to-v5-migration) to get a
file-specific compatibility plan, then the [apply migration prompt](PROMPTS.md#apply-a-v4-to-v5-migration)
to carry out the chosen upgrade. Specify whether to retain Apple images or
adopt native emoji rendering. The prompts preserve working default-picker
APIs and make optional primitive adoption a separate choice.

## Runtime and toolchain requirements

The published package now requires **Node >=18** (v4 declared >=10). Upgrade older build/server environments before installing v5; package managers with strict engine checks reject older Node versions. Browser consumers still need a supported React setup; the React peer floor remains **>=16.8**.

The published JavaScript targets **ES2020**: it ships optional chaining (`?.`) and nullish coalescing (`??`) untranspiled. Every browser released since 2020 runs it (Chrome/Edge 80, Firefox 74, Safari 13.1), as do Vite, esbuild, Rollup, Turbopack, Parcel and webpack 5. webpack 4's parser cannot read that syntax unless `node_modules` pass through Babel first; if your webpack 4 setup does not transpile dependencies, add `emoji-picker-react` to `babel-loader` or upgrade the bundler. Supporting older browsers is the application's transpilation step, as for any modern dependency.

Repository development uses **Node 24.15+ in the 24.x line**, matching CI. Storybook, Vitest, jsdom and release tooling have newer Node requirements than the published library. This contributor requirement does not raise the consumer Node or React floor. The packed-runtime CI smoke check runs the built package on Node 18.

## Common case

For many applications, the v4 component continues to work unchanged:

```tsx
import EmojiPicker, { EmojiStyle, Theme } from 'emoji-picker-react';

<EmojiPicker
  theme={Theme.DARK}
  emojiStyle={EmojiStyle.APPLE}
  onEmojiClick={handleEmoji}
/>
```

v5 additionally accepts literal values:

```tsx
<EmojiPicker
  theme="dark"
  emojiStyle="apple"
  onEmojiClick={handleEmoji}
/>
```

You do **not** need to migrate to primitives to upgrade to v5.

## At a glance

| Area | v4 | v5 |
| --- | --- | --- |
| Default emoji style | Apple images | Native glyphs (`emojiStyle="apple"` restores v4) |
| Theming | `theme` + `--epr-*` variables on `aside.EmojiPickerReact` | `colorScheme` (alias `theme`) + the same variables on any class, zero specificity |
| Own design | Override library classes | `unstyled` + `[data-epr-part]` selectors, or `emoji-picker-react/primitives` |
| Own components | Not possible | `components={{ Emoji, CategoryHeader, CategoryButton, SkinToneButton, ClearButton, ExpandButton }}` |
| Layout | Fixed | Compose `Root`, `Search`/`SearchInput`, `CategoryNav`, `Viewport`, `List`, `Preview`, `SkinTone`, `Empty`, `Loading`, `LoadError` |
| Width | `width` | `width`, or `columns` to fit a number of emojis per row |
| Search | Uncontrolled | `searchValue` / `onSearchChange`, `defaultSearchValue`, `searchLabel` |
| Localization | Datasets only | Datasets, `labels` for every UI string, loader `emojiData` for code-splitting |
| Skin tone | `defaultSkinTone` | `defaultSkinTone` or controlled `skinTone`, `skinTonePickerLocation="NONE"` |
| Suggestions | Recent / frequent | Plus `suggestedEmojis` |
| Reactions | `reactionsDefaultOpen` … | Plus `onReactionsModeChange` and `usePickerMode()` |
| Data without UI | `emojiByUnified` | Plus `emoji-picker-react/data` (`searchEmojis`, `getEmojiByUnified`) |
| Layered CSS | Specificity fights | `cssLayer="epr"` |
| Locale imports | `emoji-picker-react/dist/data/emojis-es` | `emoji-picker-react/data/emojis-es` (old path still resolves) |

## What v5 adds

### Controlled search

```tsx
const [search, setSearch] = useState('');

<EmojiPicker
  searchValue={search}
  onSearchChange={setSearch}
/>
```

This is the supported way to externally clear/synchronize the query.

The built-in search input's accessible label can now be localized independently:

```tsx
<EmojiPicker
  searchPlaceholder="Buscar"
  searchLabel="Buscar un emoji"
/>
```

### Observe reaction-mode changes

```tsx
<EmojiPicker
  reactionsDefaultOpen
  onReactionsModeChange={(reactionsOpen) => {
    updateLayout(reactionsOpen);
  }}
/>
```

This addresses applications that need to adapt surrounding layout when the compact reactions UI expands/collapses without introducing a second controlled mode API.

### Caller-defined suggestions

```tsx
<EmojiPicker
  suggestedEmojis={['1f601', '1f602', '1f603']}
/>
```

This narrowly addresses application-defined suggested emojis without replacing the existing recent/frequent localStorage behavior.

### Localize every string, control the skin tone

```tsx check
import React, { useState } from 'react';
import EmojiPicker, { SkinTones, type SkinTonesValue } from 'emoji-picker-react';

export function LocalizedPicker() {
  const [tone, setTone] = useState<SkinTonesValue>(SkinTones.NEUTRAL);
  return (
    <EmojiPicker
      labels={{ categoryNavigation: 'Categorías', skinToneNeutral: 'Tono neutro' }}
      skinTone={tone}
      onSkinToneChange={setTone}
    />
  );
}
```

## Behavior changes to review

- **Native support detection.** With the (new default) native style, the picker hides detected unsupported glyphs and broken sequences on the client, including country flags where the platform has no flag glyphs. Filtering covers the grid/search/recents, reactions, skin-tone variants and managed preview. `emojiVersion` is an additional cap, not an opt-out; choose an image style for inventory independent of OS fonts. Detection is heuristic and inconclusive probes leave the inventory visible; see [the detection contract](./API.md#5c-native-emoji-support-detection).
- **Grid semantics.** Emoji buttons in the grid carry `role="gridcell"` and category titles are `aria-hidden` (the category rowgroup carries the name). Tests that query grid emojis with `getByRole('button')` or category titles with `getByRole('heading')` should use `getByRole('gridcell')` / `getByRole('rowgroup', { name })`.
- **Emoji columns fill the row.** Leftover row width is now shared between columns instead of collecting as a gap on the right edge, so a few pixels of horizontal emoji position change (equal left/right insets). Screenshot tests that include the grid may need a refresh.
- **Fluid widths reflow.** The column count follows the picker's width when its container resizes (it was only recomputed on CSS transitions).
- **Default text contrast.** The light theme's `--epr-text-color` is `#6b6b6b` (was `#858585`) to meet WCAG AA.
- **Easier overrides.** `--epr-*` tokens are declared at zero specificity, so `.my-picker { --epr-bg-color: … }` wins without `aside.EmojiPickerReact`-style specificity. Tailwind v4 users: pass `cssLayer="epr"` and declare `@layer epr, theme, base, components, utilities;` before importing Tailwind.
- **`colorScheme` prop.** Prefer `colorScheme` over `theme` (still supported as an alias); CSS-in-JS wrappers such as Emotion, styled-components and MUI reserve `theme`.
- **Widened prop types.** Enum props (`theme`, `emojiStyle`, `suggestedEmojisMode`, …) also accept their string literals. Code that reads these props back gets the union (e.g. `ThemeValue`), not the enum; compare against string values or the enum members.
- **Unknown props are ignored.** As in v4, props the picker does not define (including removed v3 props such as `pickerStyle`; use `style`) never reach the DOM, and development builds log one `console.warn` naming them. Identifying attributes (`id`, `title`, `lang`, `dir`, `aria-*`, `data-*`) are forwarded to the root element; for event handlers, use a wrapper element or the primitives.
- **Prop updates apply after mount.** `reactions`, `previewConfig`, `hiddenEmojis`, `allowExpandReactions`, `categoryIcons`, `getEmojiUrl` and `nonce` used to be ignored after the first render.
- **Results announcement** counts what the list shows (hidden/disallowed emojis no longer counted).
- **ESM build.** `import` resolves to `dist/esm/*.mjs` (code-split; the entries share one implementation). Deep imports into `dist` other than the documented locale paths are unsupported; the raw datasets at `emoji-picker-react/src/data/*.json` remain importable (deprecated; prefer `emoji-picker-react/data`).
- **React Server Components.** The main and primitives entries are marked `"use client"`; `emoji-picker-react/data` is server-usable.

## Structural composition is opt-in

Use primitives only when you need to own macro layout/order:

```tsx
import * as EmojiPicker from 'emoji-picker-react/primitives';

<EmojiPicker.Root>
  <EmojiPicker.CategoryNav />

  <MyHeader>
    <EmojiPicker.Search />
  </MyHeader>

  <EmojiPicker.Viewport>
    <EmojiPicker.List />
  </EmojiPicker.Viewport>

  <EmojiPicker.Preview />
</EmojiPicker.Root>
```

Root renders exactly the parts supplied by the caller. Place expanded content inside Panel and Reactions outside Panel within Root when using compact reactions; Panel owns the expanded subtree’s hidden/inert state. There is no composition switch or panelProps convenience prop. Put layout attributes directly on Panel, omit unwanted controls, and conditionally mount Root to control its lifetime. Bare Root now removes decorative defaults from all managed controls; add `appearance="default"` to intentionally reuse built-in leaf styling. See [PRIMITIVES.md](./PRIMITIVES.md) for shared components and actions.

The library still owns navigation, accessibility semantics, virtualization, variations, and selection — even when you replace emoji cell or category header markup through `List components`.

## Package subpaths

v4's documentation used deep locale imports such as:

```ts
import es from 'emoji-picker-react/dist/data/emojis-es';
```

v5 introduces canonical supported package exports:

```ts
import es from 'emoji-picker-react/data/emojis-es';
```

The documented v4 path:

```ts
import es from 'emoji-picker-react/dist/data/emojis-es';
```

continues to resolve in v5 through a **deprecated compatibility export alias**. It is kept to avoid gratuitously breaking code copied from the project's own v4 documentation, but new code should use the canonical `/data/emojis-*` path.

### Undocumented deep imports

v5 introduces an explicit `exports` map. Code importing arbitrary internal `dist/*` modules may stop resolving.

That is an intentional package-boundary breaking change. Only documented/supported entry points receive compatibility guarantees.

## Existing props

v5 does **not** remove useful v4 props merely to clean up the surface.

Every v4 prop keeps working; [PROPS.md](../../PROPS.md) lists them all with their v5 defaults.

Notably retained:
- `open`
- `lazyLoadEmojis`
- `categoryIcons`
- `getEmojiUrl`
- `emojiData`
- `previewConfig`
- `searchDisabled`
- `autoFocusSearch`
- `emojiVersion`
- `skinTonesDisabled`
- `skinTonePickerLocation`
- current reactions props/callbacks

## Deprecated compatibility alias

`searchPlaceHolder` remains accepted for compatibility but `searchPlaceholder` is the canonical spelling.

Do not introduce new uses of the legacy casing.

## Changed defaults

The default `emojiStyle` is now native instead of Apple: a default
`<EmojiPicker />` renders OS glyphs without standard emoji image requests.
Native availability follows the installed font; detection filters
unsupported emoji versions before client paint, then individual sequences.
Dataset loading and any custom images or webfonts still have their own
loading requirements. Every style remains supported; to keep the previous
look, pass it explicitly:

```tsx
<EmojiPicker
  emojiStyle={EmojiStyle.APPLE}
  onEmojiClick={handleEmoji}
/>
```

The same default applies to the standalone `Emoji` component. Click
payloads still carry usable `imageUrl` values: URL resolution falls
back to Apple CDN assets when the active style has no image set.

If you supply your own images (`getEmojiUrl` on the picker or `Emoji`,
or `emojiUrl` on `Emoji`) without an `emojiStyle`, nothing changes:
a custom image source keeps v4's image default (Apple), so your resolver
is still called with `"apple"` as the style.

## React peer requirement

v5 retains the existing React peer floor of `>=16.8`. The implementation is verified against a real React 16.8 consumer, not just a static source scan.

v5 also removes v4's fixed, document-global IDs (`epr-search-id`, `epr-category-nav-id`), which collided when a page rendered two pickers. The picker renders no library-owned DOM IDs and has no `idPrefix` API. Tests or styles that targeted those IDs should use roles or `[data-epr-part]` selectors (`search-input`, `category-nav`).

## Styling

The default picker retains the existing documented CSS custom properties.

The primitives API adds a deliberately small `data-epr-part` styling surface. See [STYLING.md](./STYLING.md).

## Migration principle

A breaking release is not a requirement to break every old interface.

If an existing API remains useful and does not prevent the v5 architecture, v5 keeps it.


## Existing named exports

v5 preserves the existing main-entry exports, including `Emoji`, `emojiByUnified`, `PickerProps`, `Props`, `EmojiClickData`, `CategoryIcons`, and `CategoryConfig`.

The new `emoji-picker-react/data` API is additive; it does not replace the existing top-level `emojiByUnified`.

<!-- source: website/README.md -->

<!-- Website examples -->

# emoji-picker-react website

Demo and marketing site. Production deploys from `master`; PRs build and test the candidate static export.

```bash
# At the repository root:
npm ci
cd website
npm ci
npm run dev
```

The root prepare script builds the library before the website installs its local copy (`file:..`, `install-links=true`). After library changes, rebuild the root and reinstall the website copy. The v5 feature branch is `master-v5`; before the v5 release the site identifies itself as a preview and explains that npm latest may still be v4. Publishing npm and promoting the site are separate maintainer actions.

## API examples

The customizer emits a class-scoped CSS rule and JSX using existing public props. Its live preview remounts for geometry token changes to refresh measured rows; color-only edits preserve picker state. Use a responsive width in constrained hosts.

```tsx check
import * as React from 'react';
import EmojiPicker from 'emoji-picker-react';
export function ThemedPicker() {
  return <EmojiPicker className="my-picker" colorScheme="dark"
    width="100%" style={{ maxWidth: 320 }} columns={7} />;
}
```

Locale loaders have stable identities and load only when selected. Datasets localize emoji names/search; use `labels` to translate the interface separately.

```tsx check
import * as React from 'react';
import EmojiPicker from 'emoji-picker-react';
const loadFrench = () => import('emoji-picker-react/data/emojis-fr');
export function FrenchPicker() {
  return <EmojiPicker emojiData={loadFrench}
    labels={{ searchLabel: 'Rechercher un emoji', searchPlaceholder: 'Rechercher' }} />;
}
```

Primitive presence and placement are owned by JSX. Root inserts no Panel or Reactions, and accepts no composition/visibility switch or panelProps. Put layout on the actual part. Gallery adapters suppress initial below-fold autofocus but preserve user-initiated opening; standalone recipes keep their original behavior.

```tsx check
import * as React from 'react';
import * as Picker from 'emoji-picker-react/primitives';
export function ComposedPicker() {
  return <Picker.Root className="my-picker" style={{ height: 400 }}>
    <Picker.Reactions />
    <Picker.Panel className="my-panel">
      <Picker.Search><Picker.SkinTone /></Picker.Search>
      <Picker.CategoryNav />
      <Picker.Viewport><Picker.List /><Picker.Empty /><Picker.Loading /><Picker.LoadError /></Picker.Viewport>
      <Picker.Preview />
    </Picker.Panel>
  </Picker.Root>;
}
```

## Recipe source and prompts

Each gallery example exposes its picker-only component (`PickerExample`), picker and panel styles and setup README — never the surrounding demo app chrome. Copy a file or download it, or use **Copy implementation prompt** to include all of those files plus version-aware setup and adaptation instructions. The prompt describes the plain CSS source currently shown; other style systems require adaptation. Failed or invalid source responses offer a retry, and copy feedback belongs to the currently selected file.

## Generation and verification

- `npm run docs:llms` generates the packaged index/full guidance and identical website copies from the contracts available in this revision. CI checks all four outputs; `check:contracts` compiles the examples above from Markdown.
- `npm run designs` generates the gallery components, host adapters in its index, recipe downloads and thumbnails. `npm run registry` generates the shadcn registry item. Edit their sources, never the generated files or approved images.
- `npx playwright test --config playwright.website.config.ts` serves the built production export at `/emoji-picker-react/` and tests geometry, presets, clipboard success/failure, keyboard/focus, source fetch/download/error, locale/reset, mobile bounds and WCAG contrast. Build the website first; `WEBSITE_URL` can select an already running export.

Website tests run with the candidate build in CI. Storybook visual baselines are unchanged by website repairs.

<!-- source: stories/recipes/README.md -->

<!-- Design recipes -->

# Recipes and design examples

25 copy-paste starting points that show emoji-picker-react fitting into real
products — chat composers, comment threads, reaction bars, status dialogs,
mobile sheets, icon pickers — each implemented in **seven styling stacks**:
plain CSS, CSS Modules, Emotion, styled-components, MUI, Tailwind v4 and
shadcn/ui. All seven render pixel-identically.

Each folder is self-contained:

| File | What it is |
| :-- | :-- |
| `shell.tsx` | The demo scene: `Shell` composing a mock app around the picker |
| `picker.tsx` | The picker composition only (`PickerExample`): the root subtree, panel chrome and picker-hook helpers, with host wiring (insertion, search text, dismissal) passed in as props |
| `panel.css` | Picker panel-chrome styles for custom classes inside the composition (only recipes that have panel chrome) |
| `picker.css` | The picker's styles — the source of truth for every stack |
| `app.css` | Styles for the mock app around the picker (never part of the snippet) |
| `recipe.json` | Title, export name, root class and root component |
| `picker.module.css`, `<Name>.stories.tsx` | Generated by `npm run recipes` — do not edit |

To reuse one: copy `picker.tsx`, `picker.css` (plus `panel.css` when the
recipe has one) and render `<PickerExample />`, wiring `onEmojiClick` to
your own composer — or take the generated stack variant matching your
project from `<Name>.stories.tsx`. The mock chrome in `shell.tsx` and
`app.css` stays behind.

## Catalog

In-context product components (`Examples/*` in Storybook):

| Folder | Use case | Built with |
| :-- | :-- | :-- |
| `team-chat` | Chat message composer popover | primitives |
| `article-comments` | Comment box reaction picker | `<EmojiPicker />` |
| `status-dialog` | "Set a status" dialog with emoji field | primitives |
| `shortcode-typeahead` | `:shortcode` autocomplete under a text field | primitives, controlled `searchValue`, `useActiveEmoji` |
| `livestream-chat` | Dark livestream chat side panel | primitives |
| `project-icon-picker` | Project/page icon chooser with narrowed categories | primitives |
| `editor-insert-panel` | Document editor insert panel with vertical category rail | primitives, `CategoryNav orientation="vertical"`, `useActiveEmoji` |
| `community-forum` | Forum with custom emoji (custom group) | primitives, `customEmojis` |
| `video-call-reactions` | Video call reaction bar (dark) | `<EmojiPicker reactionsDefaultOpen colorScheme="dark" />` |
| `habit-tracker-mobile` | Mobile bottom sheet for a habit tracker | primitives |

Design-system styles:

| Folder | Style | Built with |
| :-- | :-- | :-- |
| `slack-reactions`, `github-reactions`, `imessage-tapback`, `intercom-rating` | Reaction bars and rating rows | `<EmojiPicker />` |
| `discord-sidebar`, `linear-palette`, `notion-icon-picker`, `x-composer`, `teams-fluent` | App-specific pickers | primitives |
| `material-3`, `geist-minimal`, `polaris-rating`, `windows-95` | Design-system themes | primitives |
| `ios-bottom-sheet`, `whatsapp-keyboard` | Mobile sheet / keyboard panel layouts | primitives |

All recipes follow the same rules:

- colors and sizes come from `--epr-*` tokens or plain CSS on the stable
  `[data-epr-part]` hooks; library tokens are declared at zero specificity,
  so ordinary CSS overrides them without specificity tricks (the Tailwind
  and shadcn/ui variants pass `cssLayer="epr"`);
- structural properties (viewport overflow, list/category layout, emoji cell
  geometry) are never overridden;
- behavior — keyboard navigation, focus, virtualization, variations,
  accessibility — is untouched, whatever the markup.

Coverage comes from two Playwright suites (discovered by the `recipe` tag,
so new folders are picked up automatically):

- `playwright/recipes.spec.ts` — one `<recipe>.png` baseline per recipe,
  established by the plain-CSS story. Every other stack (CSS Modules,
  Emotion, styled-components, MUI, Tailwind, shadcn/ui) is compared
  against that same file, so a stack that renders differently fails. Each
  story also gets axe (WCAG 2.1 AA) and keyboard checks.
- `playwright/recipes-interactions.spec.ts` — each recipe's plain-CSS
  story walked through every interaction state it supports (`--hover`,
  `--keyboard-focus`, `--search-results`, `--empty-search`,
  `--category-navigation`, `--skin-tone-open`, `--variations-open`,
  `--reactions-expanded`), with a functional assertion plus a screenshot
  per state. States a recipe does not have (no search box, no skin tone
  fan, no variations, non-expandable reactions) are skipped.

To add a design: copy a folder, edit `picker.css` / `shell.tsx`, run
`npm run recipes` to regenerate the seven stacks, then run the two suites
with `--update-snapshots` and look at every new image before committing.

## Composition and acceptance gates

Primitive recipes express control presence and placement through JSX. Use
`<Search><SkinTone /></Search>` for an attached tone control, or put `SkinTone`
in a consumer row. Omit it for designs without that control; do not pass the
default picker's placement/visibility switches to `Root`.

`npm run check:contracts` compiles the actual recipe shells and registry source.
Injected styling wrappers retain the appropriate `RootProps` or default-picker
prop contract, so removed props fail checking instead of being silently ignored.

CI also runs `playwright/adoption-behavior.spec.ts`: caret insertion, dismissal
and focus restoration, registry controls, nested Escape, shadow DOM, RTL,
columns and reduced motion. Arrow traversal follows composed region DOM order.

<!-- source: stories/integrations/README.md -->

<!-- Styling integrations -->

# Styling integrations

How to style the picker with popular styling stacks. Every example targets
the same public surface — `className`/`style` on parts, `--epr-*` tokens and
`[data-epr-part]` selectors — so the techniques transfer between stacks.

How the cascade works:

- the picker's tokens are declared at zero specificity, so plain CSS, CSS
  Modules, Emotion, styled-components and MUI's `styled`/`sx` override them
  without specificity tricks;
- Tailwind v4 (and anything else built on cascade layers) opts the picker
  into a layer with `cssLayer="epr"` and declares it first:
  `@layer epr, theme, base, components, utilities;` — utilities then win.

Every integration is covered by the screenshot, axe and keyboard checks in
`playwright/recipes.spec.ts`.

<!-- source: example/README.md -->

<!-- Example app -->

# emoji-picker-react example

A small Vite + React 19 app that shows every way to use the picker:

| Tab | What it shows | Files |
| --- | --- | --- |
| Batteries included | `<EmojiPicker />` with `colorScheme`, `columns` and a `--epr-*` brand theme | `src/examples/BatteriesIncluded.tsx`, `batteries.css` |
| Unstyled | `<EmojiPicker unstyled />` restyled from scratch through `[data-epr-part]` selectors | `src/examples/Unstyled.tsx`, `unstyled.css` |
| Composed | `emoji-picker-react/primitives`: your input, cells, headers, tabs and a hook-driven toolbar; a dataset loaded on demand | `src/examples/Composed.tsx`, `composed.css` |
| Data API | `searchEmojis` and `getEmojiByUnified` from `emoji-picker-react/data`, no UI | `src/examples/DataApi.tsx` |

The app consumes the library from this repository (`file:..`), so build the
library first:

```sh
npm ci && npm run build   # repository root
cd example
npm install
npm run dev
```

`npm run build` type-checks the examples and produces a production bundle.

<!-- worked example: team chat picker composition (stories/recipes/team-chat/picker.tsx; picker only, demo app chrome excluded) -->

`stories/recipes/team-chat/picker.tsx`

```tsx
import React from 'react';

import * as Picker from '../../../src/primitives';

// Chat composer popover picker: search with the skin tone control, tabs,
// the grid and a slim preview strip. Wire onEmojiClick to insert the
// chosen emoji into your own composer.
export type PickerExampleProps = {
  /** The picker root: Picker.Root, or a styled() wrapper of it. */
  Root?: React.ComponentType<Picker.RootProps>;
  className?: string;
  /** Insert `emoji.emoji` into your app. Defaults to a no-op. */
  onEmojiClick?: (emoji: Picker.EmojiClickData) => void;
};

function noopEmojiClick() {}

export function PickerExample({
  Root: RootComponent = Picker.Root,
  className,
  onEmojiClick = noopEmojiClick,
}: PickerExampleProps) {
  return (
    <RootComponent
      appearance="default"
      className={className}
      onEmojiClick={onEmojiClick}
    >
      <Picker.Search>
        <Picker.SkinTone />
      </Picker.Search>
      <Picker.CategoryNav />
      <Picker.Viewport>
        <Picker.List />
        <Picker.Empty />
      </Picker.Viewport>
      <Picker.Preview />
    </RootComponent>
  );
}
```

`stories/recipes/team-chat/picker.css`

```css
/* Team chat composer — a compact popover: indigo accents, 12px radius,
   slim preview strip. */
.chat-picker {
  --epr-bg-color: #ffffff;
  --epr-text-color: #52525b;
  --epr-highlight-color: #4f46e5;
  --epr-hover-bg-color: #f4f4f5;
  --epr-focus-bg-color: #e0e7ff;
  --epr-picker-border-color: #e4e4e7;
  --epr-search-input-bg-color: #f4f4f5;
  --epr-search-input-bg-color-active: #ffffff;
  --epr-search-border-color: transparent;
  --epr-search-border-color-active: #6366f1;
  --epr-search-input-height: 34px;
  --epr-search-input-border-radius: 8px;
  --epr-search-input-text-color: #18181b;
  --epr-search-input-placeholder-color: #71717a;
  --epr-category-label-bg-color: #fffffff2;
  --epr-category-label-text-color: #52525b;
  --epr-category-label-height: 30px;
  --epr-category-icon-active-color: #4f46e5;
  --epr-category-icon-inactive-color: #71717a;
  --epr-category-navigation-button-size: 20px;
  --epr-preview-height: 46px;
  --epr-preview-emoji-size: 26px;
  --epr-preview-text-color: #18181b;
  --epr-preview-border-color: #e4e4e7;
  --epr-emoji-size: 26px;
  --epr-emoji-padding: 5px;
  --epr-horizontal-padding: 12px;
  width: 340px;
  height: 380px;
  border: 1px solid #e4e4e7;
  border-radius: 12px;
  background: #ffffff;
  font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
}
.chat-picker [data-epr-part='search'] > * {
  padding: 12px 12px 4px;
}
.chat-picker [data-epr-part='category-nav'] > * {
  padding: 8px 12px;
}
.chat-picker [data-epr-part='category-tab'][aria-selected='true'] {
  box-shadow: 0 10px 0 -8px #4f46e5;
}
.chat-picker [data-epr-part='category-label'] {
  font-size: 12px;
  font-weight: 600;
  text-transform: none;
}
.chat-picker [data-epr-part='emoji'] {
  border-radius: 8px;
}
.chat-picker [data-epr-part='preview'] {
  font-size: 13px;
}
```