frimousse

A lightweight, unstyled, and composable emoji picker for React.

• ⚡️ Lightweight and fast: Dependency-free, tree-shakable, and virtualized with minimal re-renders
• 🎨 Unstyled and composable: Bring your own styles and compose parts as you want
• 🔄 Always up-to-date: Latest emoji data is fetched when needed and cached locally
• 🔣 No � symbols: Unsupported emojis are automatically hidden
• ♿️ Accessible: Keyboard navigable and screen reader-friendly

Installation

npm i frimousse

If you are using shadcn/ui, you can also install it as a pre-built component via the shadcn CLI.

npx shadcn@latest add https://frimousse.liveblocks.io/r/emoji-picker

Learn more in the shadcn/ui section.

Usage

Import the EmojiPicker parts and create your own component by composing them.

import { EmojiPicker } from "frimousse";

export function MyEmojiPicker() {
  return (
    <EmojiPicker.Root>
      <EmojiPicker.Search />
      <EmojiPicker.Viewport>
        <EmojiPicker.Loading>Loading…</EmojiPicker.Loading>
        <EmojiPicker.Empty>No emoji found.</EmojiPicker.Empty>
        <EmojiPicker.List />
      </EmojiPicker.Viewport>
    </EmojiPicker.Root>
  );
}

Apart from a few sizing and overflow defaults, the parts don’t have any styles out-of-the-box. Being composable, you can bring your own styles and apply them however you want: Tailwind CSS, CSS-in-JS, vanilla CSS via inline styles, classes, or by targeting the [frimousse-*] attributes present on each part.

You might want to use it in a popover rather than on its own. Frimousse only provides the emoji picker itself so if you don’t have a popover component in your app yet, there are several libraries available: Radix UI, Base UI, Headless UI, and React Aria, to name a few.

shadcn/ui

If you are using shadcn/ui, you can install a pre-built version which integrates with the existing shadcn/ui variables via the shadcn CLI.

npx shadcn@latest add https://frimousse.liveblocks.io/r/emoji-picker

It can be composed and combined with other shadcn/ui components like Popover.

Documentation

Find the full documentation and examples on frimousse.liveblocks.io.

Compatibility

• React 18 and 19
• TypeScript 5.1 and above

Miscellaneous

The name “frimousse” means “little face” in French, and it can also refer to smileys and emoticons.

The emoji picker component was originally created for the Liveblocks Comments default components, within @liveblocks/react-ui.

Credits

The emoji data is based on Emojibase.

Contributing

All contributions are welcome! If you find a bug or have a feature request, feel free to create an issue or a PR.

The project is setup as a monorepo with the frimousse package at the root and frimousse.liveblocks.io in the site directory.

Development

Install dependencies and start development builds from the root.

npm i
npm run dev

The site can be used as a development playground since it’s built with the root package via Turborepo.

npm run dev:site

Tests

The package has 95%+ test coverage with Vitest. Some tests use Vitest’s browser mode with Playwright, make sure to install the required browser first.

npx playwright install chromium

Run the tests.

npm run test:coverage

Releases

Releases are triggered from a GitHub action via release-it, and continuous releases are automatically triggered for every commit in PRs via pkg.pr.new.