emoji-picker-react 4.22.3 → 5.0.0

package/llms.txt

@@ -1,489 +1,75 @@
-# emoji-picker-react — LLM context
+# emoji-picker-react
 
-> This file is auto-generated by `npm run docs:llms`. Do not edit by hand.
-> Sources: README.md, PROPS.md, CUSTOMIZATION.md, INTERNATIONALIZATION.md, CSS_VARIABLES.md
+> 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.
 
-<!-- source: README.md -->
+Key facts:
 
-# Emoji Picker React
+- 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.
 
-The most popular fully customizable emoji picker for React.
+Exports (generated from the entry sources):
 
-[![npm downloads](https://img.shields.io/npm/dm/emoji-picker-react.svg)](https://www.npmjs.com/package/emoji-picker-react)
+- `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).
 
-**[Live Demo](https://ealush.com/emoji-picker-react)** | **[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
-
-- Fully customizable through props and CSS variables
-- Light, dark, and auto themes
-- Reactions picker mode and custom click handlers
-- Dozens of built-in languages
-- Custom image-based emojis
-- Apple, Google, Facebook, Twitter, and native emoji styles
-- Responsive and mobile-friendly
-- SSR-safe
-
-## Installation
-
-```bash
-npm install emoji-picker-react
-```
-
-## Usage
-
-```jsx
-import EmojiPicker from 'emoji-picker-react';
-
-function App() {
-  return (
-    <EmojiPicker onEmojiClick={(emojiData) => console.log(emojiData.emoji)} />
-  );
-}
-```
-
-`onEmojiClick` receives an `EmojiClickData` object (unified code, names, image URL, active skin tone) and the underlying mouse event.
-
-## Configuration
-
-```jsx
-<EmojiPicker
-  theme="dark"
-  emojiStyle="native"
-  width={320}
-  height={400}
-  previewConfig={{ showPreview: false }}
-/>
-```
-
-See [PROPS.md](PROPS.md) for the complete props reference.
-
-## Styling
-
-No stylesheet import needed. All styles are scoped via [ShipStyles](https://github.com/ealush/shipstyles) — generated class names are hashed, so the picker's CSS won't leak into or clash with your app's styles.
-
-Restyle the picker by overriding [CSS variables](CSS_VARIABLES.md) on `.EmojiPickerReact`:
-
-```css
-.EmojiPickerReact {
-  --epr-emoji-size: 32px;
-}
-```
-
-## Internationalization
-
-Pass imported locale data via the `emojiData` prop:
-
-```jsx
-import EmojiPicker from 'emoji-picker-react';
-import es from 'emoji-picker-react/dist/data/emojis-es'; // Spanish
-
-function App() {
-  return <EmojiPicker emojiData={es} />;
-}
-```
-
-See [INTERNATIONALIZATION.md](INTERNATIONALIZATION.md) for the supported languages.
-
-## Customization
-
-Custom emojis, custom category icons, preview configuration, and CSP nonces are covered in [CUSTOMIZATION.md](CUSTOMIZATION.md).
-
-## Server-Side Rendering
-
-The picker renders on the server, with styles inlined into the server HTML — no setup needed. Since the picker is usually opened on demand rather than shown immediately, lazy-loading it is still recommended to keep the initial bundle small:
-
-```javascript
-import dynamic from 'next/dynamic';
-
-const Picker = dynamic(() => import('emoji-picker-react'));
-```
-
-## Troubleshooting
-
-### `global is not defined` (Vite, versions before 4.20)
-
-Since 4.20 the picker is SSR-safe and no longer references the Node-style
-`global`. If you see `global is not defined`, upgrade to the latest version.
-On older versions only, the workaround was adding this to your HTML:
-
-```html
-<script>
-  window.global = window;
-</script>
-```
-
-## 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
-
-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.                                                       |
-| `theme`           | `Theme`      | `Theme.LIGHT`      | The visual theme. Options: `'light'`, `'dark'`, `'auto'`.                                    |
-| `emojiStyle`      | `EmojiStyle` | `EmojiStyle.APPLE` | The emoji set to use. Options: `'apple'`, `'google'`, `'facebook'`, `'twitter'`, `'native'`. |
-| `emojiVersion`    | `string`     | `null`             | Limit emojis to a specific unicode version (e.g., `"14.0"`).                                 |
-| `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`     | `undefined`        | Pass imported locale data here for internationalization. See [INTERNATIONALIZATION.md](INTERNATIONALIZATION.md). |
-
-## 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.         |
-| `style`     | `CSSProperties`      | `{}`    | Inline styles applied to the root element.            |
-| `className` | `string`             | `""`    | CSS class applied to the root element.                |
-
-Visual styling beyond size is done via [CSS variables](CSS_VARIABLES.md).
-
-## Events & Interaction
-
-| Prop               | Type                                                     | Description                                                          |
-| ------------------ | -------------------------------------------------------- | -------------------------------------------------------------------- |
-| `onEmojiClick`     | `(emojiData: EmojiClickData, event: MouseEvent) => void` | Callback triggered when a user clicks an emoji.                      |
-| `onReactionClick`  | `(emojiData: EmojiClickData, event: MouseEvent) => void` | Callback triggered when a user clicks a reaction (in reaction mode). |
-| `onSkinToneChange` | `(skinTone: SkinTones) => void`                          | Callback triggered when the user selects a new skin tone.            |
-
-## 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.                               |
-| `searchClearButtonLabel` | `string`                 | `"Clear"`                 | Aria label for the search clear button.                              |
-| `categories`             | `CategoryConfig[]`       | _(All)_                   | Array of category objects to customize order or visibility.          |
-| `suggestedEmojisMode`    | `SuggestionMode`         | `SuggestionMode.FREQUENT` | Logic for "Suggested" category. Options: `'recent'`, `'frequent'`.   |
-| `defaultSkinTone`        | `SkinTones`              | `SkinTones.NEUTRAL`       | The initial skin tone.                                               |
-| `skinTonesDisabled`      | `boolean`                | `false`                   | If true, users cannot change the skin tone.                          |
-| `skinTonePickerLocation` | `SkinTonePickerLocation` | `SEARCH`                  | Location of the skin tone trigger. Options: `'SEARCH'`, `'PREVIEW'`. |
-
-## 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'`) to hide from the picker.          |
-| `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)_ | Array of unified IDs to display in the reactions bar.                    |
-| `allowExpandReactions` | `boolean`  | `true`          | If true, shows a `+` button to switch from reactions to full picker.     |
-
-<!-- source: CUSTOMIZATION.md -->
-
-# Customization
-
-## 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:
-
-### 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):
+Quick reference:
 
 ```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 (i18n)
-
-Import the dictionary you need and pass it to the `emojiData` prop:
-
-```javascript
+// Batteries included: theme the built-in look with colorScheme and --epr-* variables.
 import EmojiPicker from 'emoji-picker-react';
-import es from 'emoji-picker-react/dist/data/emojis-es'; // Spanish
-
-function App() {
-  return <EmojiPicker emojiData={es} />;
-}
-```
-
-## 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: CSS_VARIABLES.md -->
-
-# 🎨 CSS Variables
-
-You can customize specific parts of the picker by overriding these CSS variables. Target `.EmojiPickerReact` or `aside.EmojiPickerReact` to apply them.
-
-```css
-.EmojiPickerReact {
-  --epr-emoji-size: 32px;
-}
-```
-
-or
-
-```css
-aside.EmojiPickerReact {
-  --epr-emoji-size: 32px;
-}
-```
-
-## 🎛️ General Variables
-
-| Variable                     | Description                                        | Default   |
-| :--------------------------- | :------------------------------------------------- | :-------- |
-| `--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.                                   | `#858585` |
-| `--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-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)` |
-
-## 🖐️ 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`                  |
+<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, … }
+```
+
+## Docs
+
+- [Agent integration guide](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/AGENT_GUIDE.md): installed-version discovery, batteries included/BYOD, typed input/cell contracts, localization and verification
+- [Copyable integration prompts](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/PROMPTS.md): setup, brand styling, design-library composition, recipe adoption and v4-to-v5 migration
+- [README](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/README.md): overview, quick start, choosing a path, styling with any solution, common tasks
+- [Props reference](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/PROPS.md): every prop of the default <EmojiPicker />
+- [CSS variables](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/CSS_VARIABLES.md): every --epr-* design token
+- [Customization](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/CUSTOMIZATION.md): custom emojis and groups, category icons, preview, CSP nonce
+- [Internationalization](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/INTERNATIONALIZATION.md): locale datasets and labels
+- [Adoption](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/ADOPTION.md): native input, loading recovery, registry installation and source downloads
+- [v5 API](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/API.md): all v5 additions with examples
+- [Primitives](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/PRIMITIVES.md): composable parts, hooks, custom cells, grammar
+- [Styling](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/STYLING.md): tokens, parts, cascade, structural rules
+- [Styling recipes by library](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/STYLING_RECIPES.md): theme, unstyled and composed snippets for plain CSS, CSS Modules, Tailwind, shadcn/ui, Emotion, styled-components and MUI
+- [Data API](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/DATA_API.md): framework-free search and lookup
+- [Migrating from v4](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/docs/v5/MIGRATION.md): what changed and how to upgrade
+- [Website examples](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/website/README.md): typed customization, locale loading and composition
+
+## Examples
+
+- [Design recipes](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/stories/recipes/README.md): 25 designs, each in seven styling stacks
+- [Styling integrations](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/stories/integrations/README.md): shadcn/ui, Tailwind, Emotion, styled-components, CSS Modules, CSS, MUI
+- [Example app](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/example/README.md): Vite + React 19 app running the batteries-included, unstyled, composed and data-API paths
+
+## Optional
+
+- [llms-full.txt](https://raw.githubusercontent.com/ealush/emoji-picker-react/master/llms-full.txt): the complete documentation in one file