expo-native-sheet-emojis

v2.0.1

Published

11 days ago

A fully native emoji picker bottom sheet for React Native. Built with Swift and Kotlin for maximum performance. Features search with multilingual keywords, skin tones, frequently used tracking, theming, and configurable layout.

0High
0Medium
0Low

efstathiosntonas

expo react-native emoji picker bottom-sheet native ios android keyboard input

expo-native-sheet-emojis

A fully native emoji picker bottom sheet for React Native. Built entirely in Swift (iOS) and Kotlin (Android) -- every interaction runs at 60+ FPS with zero bridge overhead.

Highlights

1900+ emojis across 9 categories (Unicode Emoji up to v16.0), rendered at 60+ FPS
60+ FPS everywhere -- native UICollectionView (iOS) and RecyclerView (Android) with no JS bridge involvement during scrolling, searching, or animations
Fully native on both platforms -- no JavaScript emoji rendering, no web views, no React re-renders
Search across 21 languages powered by Unicode CLDR -- the industry-standard source for emoji annotations used by iOS, Android, and major platforms. Runs on a background thread to keep the UI thread free
Bottom sheet with configurable snap points and smooth spring animations
Skin tone selection with long-press gesture
Frequently used tracking persisted across app launches
Structured theming with light/dark presets and full custom theme support
Configurable grid layout (columns, emoji size)
Floating pill category bar (bottom) or inline strip (top)
Expo config plugin for per-locale translation bundling -- English-only apps pay zero extra bundle size

Demo

| iOS | Android | |-|-| | | |

Installation

npx expo install expo-native-sheet-emojis

For bare workflow projects, run npx expo prebuild after installation.

For bare React Native projects, you must ensure that you have installed and configured the expo package before continuing.

yarn add expo-native-sheet-emojis
cd ios && pod install

Quick Start

The imperative API presents a native bottom sheet and returns the selected emoji:

import { EmojiSheetModule } from 'expo-native-sheet-emojis';

async function pickEmoji() {
  const result = await EmojiSheetModule.present({
    theme: 'dark',
    categoryBarPosition: 'top',
    layoutDirection: 'auto',
  });

  if (!result.cancelled) {
    console.log('Selected:', result.emoji);
  }
}

Declarative Usage

Embed the emoji picker directly in your component tree:

import { EmojiSheetView } from 'expo-native-sheet-emojis';

function MyComponent() {
  return (
    <EmojiSheetView
      style={{ flex: 1 }}
      theme="light"
      layoutDirection="auto"
      onEmojiSelected={(emoji, name, id) => console.log(emoji, name, id)}
      columns={7}
      showSearch={true}
    />
  );
}

Theming

Use the built-in presets or provide a full custom theme object:

import { EmojiSheetModule, lightTheme, darkTheme } from 'expo-native-sheet-emojis';

// Preset themes
await EmojiSheetModule.present({ theme: 'dark' });
await EmojiSheetModule.present({ theme: lightTheme });

// Custom theme
await EmojiSheetModule.present({
  theme: {
    backgroundColor: '#1A1A2E',
    searchBarBackgroundColor: '#2A2F39',
    textColor: '#FFFFFF',
    textSecondaryColor: '#999999',
    accentColor: '#EA4578',
    dividerColor: '#3A3A4A',
  },
});

Custom Hook Pattern

For apps that use the emoji picker in multiple places, extract a reusable hook to centralize theme, translations, and configuration:

import { EmojiSheetModule } from 'expo-native-sheet-emojis';
import type { EmojiSheetPresentOptions, EmojiSheetResult } from 'expo-native-sheet-emojis';

export function useEmojiPicker() {
  // Pull your theme colors and i18n strings from your app's providers
  const theme = useAppTheme();
  const { t } = useTranslation();

  const present = async (
    overrides?: Partial<EmojiSheetPresentOptions>
  ): Promise<EmojiSheetResult> => {
    return EmojiSheetModule.present({
      theme: {
        accentColor: theme.colors.primary,
        backgroundColor: theme.colors.background,
        searchBarBackgroundColor: theme.colors.surface,
        textColor: theme.colors.text,
        textSecondaryColor: theme.colors.textSecondary,
        dividerColor: theme.colors.border,
      },
      translations: {
        searchPlaceholder: t('Search emoji'),
        noResultsText: t('No emojis found'),
        categoryNames: {
          frequently_used: t('Frequently Used'),
          smileys_emotion: t('Smileys & Emotion'),
          people_body: t('People & Body'),
          animals_nature: t('Animals & Nature'),
          food_drink: t('Food & Drink'),
          travel_places: t('Travel & Places'),
          activities: t('Activities'),
          objects: t('Objects'),
          symbols: t('Symbols'),
          flags: t('Flags'),
        },
      },
      excludeEmojis: ['pile_of_poo'],
      ...overrides,
    });
  };

  return { present };
}

Then use it anywhere with a single line:

const emojiPicker = useEmojiPicker();

const result = await emojiPicker.present();
if (!result.cancelled) {
  console.log(result.emoji);
}

Multilingual Search

English search keywords are always included (built into emojis.json). No additional setup is needed for English-only apps.

To enable search in additional languages, use the Expo config plugin to select which locale files to bundle. Nothing is bundled by default -- you opt in to the locales you need.

Expo (managed or prebuild)

Configure the plugin in your app.json or app.config.js:

{
  "plugins": [
    ["expo-native-sheet-emojis", { "searchLocales": ["es", "fr", "de", "ja"] }]
  ]
}

Then run npx expo prebuild --clean. The plugin copies only the selected locale files into your native bundles.

Bare React Native

Android requires no setup -- the module's Gradle build automatically copies all translation files at build time.

iOS requires a pre_install hook in your Podfile. This copies locale files into the module's bundle during pod install:

All locales:

pre_install do |installer|
  emoji_sheet_pod = File.join(__dir__, '..', 'node_modules', 'expo-native-sheet-emojis')
  source = File.join(emoji_sheet_pod, 'translations')
  target = File.join(emoji_sheet_pod, 'ios', 'translations')
  if File.directory?(source)
    FileUtils.mkdir_p(target)
    FileUtils.cp(Dir.glob(File.join(source, '*.json')), target)
  end
end

Selected locales only:

pre_install do |installer|
  emoji_locales = ['es', 'fr', 'de', 'ja']
  emoji_sheet_pod = File.join(__dir__, '..', 'node_modules', 'expo-native-sheet-emojis')
  source = File.join(emoji_sheet_pod, 'translations')
  target = File.join(emoji_sheet_pod, 'ios', 'translations')
  if File.directory?(source)
    FileUtils.mkdir_p(target)
    files = emoji_locales.map { |l| File.join(source, "#{l}.json") }.select { |f| File.exist?(f) }
    FileUtils.cp(files, target)
  end
end

If you already have a pre_install block, add the emoji translation snippet inside it. Run pod install after updating.

Supported Locales

ca, cs, de, el, en, es, fi, fr, hi, hu, it, ja, ko, nl, pl, pt, ru, sv, tr, uk, zh

Bundle size impact: The base emoji data (emojis.json) adds ~300KB to your app. Each locale file adds 64-185KB depending on the language (all 21 locales total ~2.3MB). Only bundle the locales your app actually needs.

Custom Translations

You can create your own translation files for languages not included in the package, or override existing translations with custom keywords.

Each translation file is a JSON object mapping emoji characters to arrays of search keywords:

{
  "\u2764\uFE0F": ["love", "heart", "red heart"],
  "\uD83D\uDE00": ["happy", "grin", "smile"],
  "\uD83D\uDC4D": ["thumbs up", "like", "approve"]
}

The keys are emoji characters (as Unicode strings) and the values are arrays of search keywords in your target language. The native search engine will match user input against these keywords.

To add a custom translation:

Create a .json file following the format above (e.g., th.json for Thai)
Place it in the native translations directory:
- iOS: Add to the module's translations/ bundle directory in Xcode
- Android: Place in android/app/src/main/assets/translations/
The native code automatically picks up all .json files in the translations directory -- no code changes needed

To generate a translation file from CLDR data:

The package includes a maintainer script that generates translation files from Unicode CLDR annotation data:

cd node_modules/expo-native-sheet-emojis
yarn add --dev cldr-annotations-full
node scripts/build-emoji-translations.mjs

This produces per-locale files in translations/ for all 21 supported languages. You can modify the SUPPORTED_LOCALES array in the script to add new languages that CLDR supports.

API Reference

EmojiSheetModule.present(options?)

Presents the emoji picker as a native bottom sheet. Returns a promise that resolves when the user selects an emoji or dismisses the sheet.

Parameters:

Returns: Promise<EmojiSheetResult>

The result is a discriminated union:

{ emoji: string; name: string; id: string } when an emoji is selected
{ cancelled: true } when the sheet is dismissed without selection

EmojiSheetModule.dismiss()

Programmatically dismisses the emoji picker sheet.

Returns: Promise<void>

EmojiSheetModule.clearRecents()

Clears all frequently used emoji data.

Returns: Promise<void>

EmojiSheetModule.clearSkinTonePreferences()

Clears all saved skin tone preferences.

Returns: Promise<void>

EmojiSheetView

A declarative React component that renders the emoji picker inline.

Props:

EmojiSheetTheme

All theme fields with their purpose:

EmojiSheetTranslations

EmojiSheetPresentOptions

EmojiSheetResult

A discriminated union type:

type EmojiSheetResult =
  | { emoji: string; name: string; id: string; cancelled?: never }
  | { cancelled: true; emoji?: never; name?: never; id?: never };

Category Bar Position

The category bar can be placed at the top or bottom of the picker.

Top (default): The category icons appear directly below the search bar. This mirrors the layout used by most native platform emoji keyboards.
Bottom: The category icons float in a rounded pill at the bottom of the sheet with a blur backdrop (iOS) or elevated shadow (Android). This layout is familiar to users of chat applications like Slack and Discord.

Set via categoryBarPosition: 'top' or categoryBarPosition: 'bottom' in the options.

Layout Direction

The picker supports automatic and forced layout direction:

auto (default): Follows the device locale/layout direction
ltr: Forces a left-to-right layout
rtl: Forces a right-to-left layout

This affects the search bar, category strip, sticky category headers, and overall picker chrome on both iOS and Android.

await EmojiSheetModule.present({
  layoutDirection: 'rtl',
});

Configuration Props

LLM / AI Agent Reference

If you're an AI agent or using an LLM to integrate this module, see llms.txt for a concise, structured reference with all types, APIs, and usage patterns.

Contributing

Contributions are welcome! Please read the contributing guide before submitting a pull request.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

expo-native-sheet-emojis

Highlights

Demo

Installation

Quick Start

Declarative Usage

Theming

Custom Hook Pattern

Multilingual Search

Expo (managed or prebuild)

Bare React Native

Supported Locales

Custom Translations

API Reference

EmojiSheetModule.present(options?)

EmojiSheetModule.dismiss()

EmojiSheetModule.clearRecents()

EmojiSheetModule.clearSkinTonePreferences()

EmojiSheetView

EmojiSheetTheme

EmojiSheetTranslations

EmojiSheetPresentOptions

EmojiSheetResult

Category Bar Position

Layout Direction

Configuration Props

LLM / AI Agent Reference

Contributing

License