Quickstart

Get a key, install the SDK, search and ship a picker in about five minutes.

On this page

You will get a key, install one package, run a search and put a picker on the page. Pick your stack in the code tabs: the choice carries over to every block on this page.

Get a key
Open the dashboard and sign in with GitHub. Create an app, then choose Create key and Publishable key. Add the origins your app runs on, for example http://localhost:5173 and https://your.app. The key works only from those origins.
The Free plan needs no card. You can also skip this step for now: without a key, the API applies a stricter rate limit per IP.
Install
```
npm install @emojisense/react frimousse
```
```
npm install @emojisense/web-component
```
```
npm install emojisense
```
React apps get hooks and a ready picker. The web component works in Vue, Svelte, Angular and plain HTML. The emojisense package is the engine alone, with no dependencies.

Search

The first search runs as soon as the English core pack arrives. Every keystroke is answered on the device. When the dictionary is unsure, the API adds meaning results a moment later.

import { useState } from "react";
import { useEmojiSearch, useEmojisense } from "@emojisense/react";

export function EmojiSearch() {
  const [query, setQuery] = useState("");
  const sense = useEmojisense({
    packBaseUrl: "https://api.emojisense.com/v1/pack/0.1.0",
    endpoint: "https://api.emojisense.com",
    publishableKey: "pk_live_…",
  });
  // Results on every keystroke; meaning results merge in when unsure.
  const { results } = useEmojiSearch(query, sense, { limit: 8 });

  return (
    <>
      <input
        value={query}
        onChange={(event) => setQuery(event.target.value)}
        placeholder="Search emoji…"
      />
      <p>{results.map((result) => result.emoji).join(" ")}</p>
    </>
  );
}

import "@emojisense/web-component";

// The picker (next step) searches as people type. You can also set the query yourself:
const picker = document.querySelector("emojisense-picker");
picker.query = "jurassic park"; // sets the search text and searches

// Once picker.status is "ready", picker.engine is the on-device engine.

import { createEngine, loadPacks } from "emojisense";

const packs = await loadPacks({ baseUrl: "https://api.emojisense.com/v1/pack/0.1.0" });
const engine = createEngine(packs);

const { results } = engine.search("jurassic park", { limit: 3 });
console.log(results.map((result) => result.emoji).join(" "));
// 🦖 🦟 🚙

Add a picker

The picker shows every emoji by category. As soon as someone types, it shows the Emojisense ranking, with keyboard navigation and skin tones.

import { useEmojisense } from "@emojisense/react";
import { EmojisensePicker } from "@emojisense/react/frimousse";

export function EmojiPicker({ onPick }: { onPick: (emoji: string) => void }) {
  const sense = useEmojisense({
    packBaseUrl: "https://api.emojisense.com/v1/pack/0.1.0",
    endpoint: "https://api.emojisense.com",
    publishableKey: "pk_live_…",
  });

  return (
    <EmojisensePicker
      emojisense={sense}
      onEmojiSelect={({ emoji }) => onPick(emoji)}
    />
  );
}

<emojisense-picker
  pack-url="https://api.emojisense.com/v1/pack/0.1.0"
  endpoint="https://api.emojisense.com"
  key="pk_live_…"
></emojisense-picker>

<script type="module">
  // With a bundler. Without one, load dist/emojisense-picker.js instead.
  import "@emojisense/web-component";

  const picker = document.querySelector("emojisense-picker");
  picker.addEventListener("emoji-select", (event) => {
    const { emoji, label, id } = event.detail; // e.g. "👍🏽", "thumbs up", "1F44D"
  });
</script>

import {
  createEngine,
  createSearchSession,
  createSemanticClient,
  loadPacks,
} from "emojisense";

const packs = await loadPacks({ baseUrl: "https://api.emojisense.com/v1/pack/0.1.0" });
const engine = createEngine(packs);
const session = createSearchSession({
  engine,
  semantic: createSemanticClient({
    endpoint: "https://api.emojisense.com",
    key: "pk_live_…",
  }),
  onChange: (state) => render(state.results), // your own grid
});

input.addEventListener("input", () => session.update(input.value));

Frimousse is unstyled, so style it like any Frimousse picker, or use the shadcn/ui component. The web component has its own theme.

Try it
Type these into your picker. The emoji below are the real top results of the on-device engine with the English core and extension packs.
- “ship it”🚀 📦️ 🚢
- “greatest of all time”🐐 🧔‍♀️ 🤹
- “i'm exhausted”🛌 🪫 😮‍💨
- “hallowelen” · typo🎃 🧛 🐈‍⬛
- “break a leg”🍀 🎭️ 🦵

Get a key

Install

Search

Add a picker

Try it

Next steps