Emoji Picker

The emoji picker requires React and Tailwind CSS to function. Install the package using your preferred package manager:

bun add @ferrucc-io/emoji-picker
# or
yarn add @ferrucc-io/emoji-picker
# or
npm i @ferrucc-io/emoji-picker
# or
pnpm add @ferrucc-io/emoji-picker

Because the component uses Tailwind CSS, you must ensure your Tailwind configuration includes the component's styles.

For Tailwind v4.x: Add the @source directive to your CSS file containing your Tailwind configuration.

For Tailwind v3.x: Add the component's distribution path to the content array in your tailwind.config.ts.

// If you're using Tailwind v4.x
// In your CSS file containing your tailwind configuration
@source "../node_modules/@ferrucc-io/emoji-picker";

// If you're using Tailwind v3.x
// In your tailwind.config.ts
"content": [
  // Keep the existing content array
  // Add this line:
  "./node_modules/@ferrucc-io/emoji-picker/dist/**/*.{js,jsx,ts,tsx}",
],

The EmojiPicker is a composable component. You build the UI by nesting sub-components like Header, Input, Group, and List.

<EmojiPicker onEmojiSelect={handleEmojiSelect}>
  <EmojiPicker.Header>
    <EmojiPicker.Input placeholder="Search emoji" />
  </EmojiPicker.Header>
  <EmojiPicker.Group>
    <EmojiPicker.List />
  </EmojiPicker.Group>
</EmojiPicker>

The renderHeader prop allows you to take full control over how section headers are rendered. It provides content (the header text/element) and isSticky (boolean indicating if the header is currently stuck to the top).

import type { HeaderRendererProps } from '@ferrucc-io/emoji-picker';

function MyHeader({ content, isSticky }: HeaderRendererProps) {
  return (
    <div className={isSticky ? 'bg-white/95 backdrop-blur-sm' : 'bg-transparent'}>
      {content}
    </div>
  );
}

<EmojiPicker renderHeader={MyHeader}>
  {/* ... */}
</EmojiPicker>

Use these interfaces to define your custom emoji data structures.

interface CustomEmoji {
  id: string;
  name: string;
  imageUrl: string;
  category?: string;
}

interface CustomSection {
  id: string;
  name: string;
  emojis: (EmojiMetadata | CustomEmoji)[];
  priority?: number; // Lower values appear first (defaults to 999)
}

The base EmojiPicker component accepts the following props for customization:

interface EmojiPickerProps {
  emojisPerRow?: number;      // Number of emojis per row
  emojiSize?: number;         // Size of each emoji in pixels
  containerHeight?: number;    // Height of the emoji container
  maxUnicodeVersion?: number; // Maximum Unicode version to include (defaults to 16.0). Hides unsupported emojis.
  onEmojiSelect?: (emoji: string) => void; // Callback when emoji is selected
  customSections?: CustomSection[]; // Custom image-based emoji sections
  frequentlyUsedEmojis?: (string | CustomEmoji)[]; // Emojis to show in a "Frequently Used" section at the top
  renderHeader?: (props: HeaderRendererProps) => React.ReactNode; // Custom renderer for section headers
}

The EmojiPickerPreview component accepts the following props:

The EmojiPicker component is the primary entrypoint for the library. It provides a context-wrapped container that manages emoji state, selection, and configuration. It uses jotai internally for state management.

To use it, wrap your desired sub-components (like EmojiPicker.Input, EmojiPicker.List, etc.) inside the EmojiPicker component. You can customize the picker's behavior via props such as onEmojiSelect, emojisPerRow, and emojiSize.

import { EmojiPicker } from '@ferrucc-io/emoji-picker';

function MyComponent() {
  return (
    <EmojiPicker 
      onEmojiSelect={(emoji) => console.log('Selected:', emoji)}
      emojisPerRow={6}
      emojiSize={24}
    >
      <EmojiPicker.Input />
      <EmojiPicker.List />
    </EmojiPicker>
  );
}

The EmojiPicker component exposes several static sub-components that must be used within the EmojiPicker provider to access the shared state. These include:

• EmojiPicker.Input: The search input field.
• EmojiPicker.Group: A container for grouping emojis.
• EmojiPicker.List: The main list of emojis.
• EmojiPicker.Preview: A preview area for the currently selected or hovered emoji.
• EmojiPicker.Content: Uses EmojiPickerSmartContent for intelligent emoji rendering.
• EmojiPicker.SkinTone: Controls or displays skin tone variations.
• EmojiPicker.Header: A specialized header component for the picker.

The EmojiPickerList component is a memoized component used to render the emoji selection interface, handling both category browsing and search results. It supports the following props for customization:

• hideStickyHeader (boolean, optional): If set to true, the sticky header in the list will be hidden. Defaults to false.
• containerHeight (number, optional): Sets the height of the emoji container. Defaults to 364.

Note: The component automatically switches between displaying EmojiCategories when the search input is empty and EmojiSearchResults when a search term is present.

import { EmojiPickerList } from '@ferrucc-io/emoji-picker';

// Example usage with custom height and no sticky header
<EmojiPickerList hideStickyHeader={true} containerHeight={400} />