# emoji-picker-react — LLM context

> 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

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

# Emoji Picker React

The most popular fully customizable emoji picker for React.

[![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)** | **[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):

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