Emoji picker

Default density Compact density Restart from the initial state Show the copyable source

Usage

The value is the emoji sequence itself, with the skin tone applied, and it submits with a form under name. Typing filters by name and keywords, the arrow keys move through the grid and Enter picks. The grid is virtualized, so a full dataset of several thousand emoji stays fast. Without data the picker uses a compact English dataset that covers every standard category, and it hides emoji newer than the platform can draw. Country flags are hidden where the platform draws them as letters. Set emojiVersion to cap the versions yourself.

Every pick dispatches tp-action with the emoji and its record, even when the same emoji is picked again. A pick that changes the value also proposes a cancelable tp-value-change, followed by tp-value-commit. Cancelling tp-action leaves the value and the popup unchanged. Supply value for a controlled picker or defaultValue for an uncontrolled one; the mode stays fixed for the element’s lifetime. The same rule applies to the query, skinTone and open lanes.

Default density Compact density Restart from the initial state Show the copyable source

Status: 🎧 Headphone

Popup

picker="popup" renders a trigger Button showing the current emoji and opens the picker in a Popover. A pick closes it; cancel the tp-open-change with reason item-press to keep it open for several picks, as a message composer does. The trigger, Escape and outside presses still close it. Put your own trigger in the trigger slot to replace the Button.

Default density Compact density Restart from the initial state Show the copyable source

Skin tone

The skin tone Button in the footer opens a menu of tones. Emoji that accept a tone show it in the grid, the preview and their names, and picks carry it. default-skin-tone sets the starting tone: none, light, medium-light, medium, medium-dark or dark. The widget does not remember the choice, so store the tone from tp-skin-tone-change and pass it back next time; skin-tone makes it controlled.

Default density Compact density Restart from the initial state Show the copyable source

Saved tone: medium

Set skin-tone-selector="false" to hide the Button when tones do not apply.

Recent emoji

recent is a property listing emoji to show in a Recent category at the top. The widget keeps no history of its own, so the application decides what counts as recent and where it is stored: per device, per account or per workspace. Entries the dataset does not know are skipped. The Recent category is hidden while searching.

Default density Compact density Restart from the initial state Show the copyable source

Custom emoji

custom takes groups of the application’s own image emoji, each with an id, label and emojis. Every custom emoji has an id, a label, optional keywords and an image src. Custom groups follow Recent and precede the dataset categories, they are searchable by label and keywords, and a custom pick publishes :id: as its value, which recent accepts too. icon sets the group’s category bar icon; without it the first image is used.

Default density Compact density Restart from the initial state Show the copyable source

Datasets

data takes a dataset, or a function that loads one per locale; the picker shows a loading state and a Retry action while a source loads or fails. A dataset lists categories in display order and emojis, each with its emoji, label, keywords and category. A small, curated set suits a reaction bar, together with category-bar="false", preview="false" and fewer columns. The picker calls a source after it connects, when data or locale changes and on reload(), aborting the previous call. Every status change dispatches tp-loading-status-change with { status, error }.

Default density Compact density Restart from the initial state Show the copyable source

The @tweakpad/ui/emoji entry point holds the dataset helpers. builtinEmojiData() returns the built-in dataset, getEmojiDetails() looks up the record of a sequence (toned or not) for showing a reaction’s name, and applySkinTone() and stripSkinTone() convert stored values. For the full Unicode set in another language, createEmojibaseSource() loads Emojibase data files from a URL you host, per locale, and caches them in local storage; createEmojibaseData() converts files you bundle yourself. The library never imports Emojibase itself. The locale comes from locale (or the document language) and falls back to English when the dataset does not publish it. Concurrent pickers share one load.

Here the source reads the published emojibase-data package from a public CDN, which brings every Unicode emoji with its skin tones and search keywords. While the files load the picker shows its loading state, and if the request fails it offers Retry; later visits read from the cache.

Default density Compact density Restart from the initial state Show the copyable source

In a field

The picker is a form control: the emoji submits under name, required validates, and Reset restores default-value. Inside a Field, the label names the picker and the Field shows its error.

Default density Compact density Restart from the initial state Show the copyable source

Save status Reset

Pick an emoji, then save.

Sizes and states

Default density Compact density Restart from the initial state Show the copyable source

readonly keeps focus, browsing and form submission but blocks picks; disabled removes all three. The list shows seven rows by default and fills a block size you set on the picker. Emoji glyphs use the --tp-font-emoji role, which you can point at an emoji web font.

Categories

The category bar is a row of icon tabs, one per category, underlined like variant="underline" Tabs; a Tooltip names the tab under the pointer or focus. The selected category follows the top of the list; pressing one scrolls its label to the top and highlights its first emoji, clearing an active search, and it stays selected until the list scrolls or the highlight moves. scrollToCategory(id) does the same from code. Category labels stay at the top of the list while their category scrolls; sticky="false" turns that off. category-bar="false" hides the bar.

Keyboard

Focus stays in the search field while the highlight moves through the grid.

KeyActionDown, UpNext or previous row, keeping the column; the first emoji when nothing is highlightedLeft, RightPrevious or next emoji in the row, following the writing directionHome, EndFirst or last emojiEnterPick the highlighted emojiTabMove to the skin tone Button and the footerArrows in the category barMove between categories; Enter or Space jumpsEnter on the skin toneOpen the tone menu; arrows move, Enter chooses, Escape closes

Hovering an emoji with a mouse highlights it; pressing it picks it without moving focus.

Constituents and accessibility

The search field is a combobox named “Search emoji” that points its active descendant at the highlighted emoji. The grid is a listbox named by label; each category is a group named by its label, and each emoji is an option named by its name (and tone) with its position in the whole list. A polite status announces the number of matches, loading and errors; tone changes are announced. The category bar is a tab list named “Categories” whose tabs are named by their categories. The skin tone Button is named by “Skin tone” and the current tone and opens a menu of radio items with the current tone checked. The preview and custom images are decorative. Only the rows near the visible part of the list are rendered, so large datasets stay fast.

API Reference

Every element also accepts motion-policy.