# Emoji Picker

A grid of selectable emoji, typically shown inside a Popover.

- Category: Core Elements
- Page: https://wunderui.com/components/emoji-picker
- Tier: Free

## Install

```bash
npx wunderui-cli add emoji-picker
```

## Import

```tsx
import { EmojiPicker } from "@/components/wunderui/emoji-picker"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { EmojiPicker } from "@/components/ui/emoji-picker"

export function Reactions() {
  const [picked, setPicked] = useState<string | null>(null)

  return (
    <div className="flex flex-col items-center gap-3">
      <EmojiPicker onSelect={setPicked} />
      <p>Picked: {picked ?? "nothing yet"}</p>
    </div>
  )
}
```

Expected result: You see a card with twelve emoji in two rows of six. Press one and its emoji appears after the word Picked.

## Usage

```tsx
import { useState } from "react"
import { EmojiPicker } from "@/components/ui/emoji-picker"

export function Example() {
  const [picked, setPicked] = useState<string | null>(null)

  return (
    <div className="flex flex-col items-center gap-3">
      <EmojiPicker onSelect={setPicked} />
      <p className="text-sm text-text-secondary">Picked: {picked ?? "nothing yet"}</p>
    </div>
  )
}
```

## When to use

### Use Emoji Picker for

- Reactions under a message, a comment or a post, where one tap adds an emoji
- A short, curated set of emoji to label or mood-tag something
- Inserting an emoji into a comment box or a status line

### Use something else

- [Rating](https://wunderui.com/components/rating) for a score from one to five rather than a free choice of emoji
- [Combobox](https://wunderui.com/components/combobox) for a long list that people search by typing
- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for a list of actions with text labels

## Keyboard

Every emoji is a native button, so the browser provides focus and activation. The picker adds no arrow key navigation: each button is one tab stop.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous emoji, left to right and top to bottom. |
| `Enter` or `Space` | Picks the focused emoji and calls `onSelect` with it. |
| `Escape` | In a Popover: closes it and returns focus to the trigger. The picker itself does nothing on Escape. |

## Behavior

What the picker does with state, layout, names and motion.

- **No state:** The picker does not remember a pick, show a selected emoji or close anything. Every press hands you the emoji, and what follows is yours: store it, insert it, close the Popover.
- **Layout:** Six columns with 4 px between them, 32 px buttons and 8 px of padding. Fewer than six emoji leave the panel 230 px wide, more than six wrap onto new rows, and there is no maximum height or scrolling.
- **Names:** The group is named Emoji and each button is named by its emoji, so a screen reader reads the standard name, such as fire. A custom picture is not announced like that, so use real emoji characters.
- **The default set:** By default the picker shows twelve: grinning face, tears of joy, heart eyes, thumbs up, folded hands, fire, party popper, red heart, crying face, open mouth, clapping hands and rocket.
- **Surface:** The panel uses the popover surface with a border and a large shadow, because it normally floats. Inside a card you can lay it flat by removing the shadow.
- **Motion:** The picker has no motion of its own: hover and pressed fills change at once. A Popover around it fades and scales in, and out a step faster.
- **Reduced motion:** With reduced motion the Popover keeps its fade and drops the scale. The picker has nothing to remove.

## Anatomy

- `EmojiPicker`: A panel with a grid of emoji buttons, in a group named Emoji. It keeps no state: it hands the pressed emoji to your handler and you decide what happens next.
- `Panel`: The card around the grid: a border, the popover surface, a shadow and 16 px corners. Six columns with 4 px between them and 8 px of padding make a row 230 px wide.
- `Emoji button`: A 32 px button with 8 px corners, named by its emoji. Hover fills it with the page tone, pressed with the subtle tone, and keyboard focus shows the indigo border and 2 px ring.

## Best practices

### Do

- Put the picker inside a Popover opened by an icon button and close it on pick. The picker draws its own card, so strip the border, background, padding and shadow from the popover content.
- Pass a short list of emoji in a fixed order. The grid has six columns, so 6, 12 or 18 emoji fill every row.
- Give the trigger an accessible name such as Add a reaction. The picker names its own buttons by their emoji, but the button that opens it needs words.

### Don't

- Don't use it as an emoji keyboard. It shows only the emoji you pass: no search, categories, skin tones or recently used.
- Don't use an emoji as the only information in a control. The buttons are named by the emoji alone, so keep visible text where the meaning matters.
- Don't expect it to close anything. The picker does not know about the Popover it sits in, so a pick leaves it open until you close it.

## API reference

### EmojiPicker

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the panel, for example `shadow-none` inside a card or a different `grid-cols-*`. |
| emojis | string[] | DEFAULT_EMOJIS | The emoji to show, one string each, in order. Defaults to twelve common reactions. The grid has six columns, so a multiple of six fills every row. Each emoji must be unique, because it is the key. |
| onSelect | (emoji: string) => void |  | Called with the emoji that was pressed. The picker keeps no selection, so store the emoji, insert it or close the Popover here. |

## Examples

### Placement: the picker below or above its trigger

```tsx
import { useState } from "react"
import { SmilePlus } from "lucide-react"
import { EmojiPicker } from "@/components/ui/emoji-picker"
import { IconButton } from "@/components/ui/icon-button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export function Example() {
  const [open, setOpen] = useState(false)

  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger render={<IconButton variant="plain" aria-label="Add a reaction" />}>
        <SmilePlus />
      </PopoverTrigger>
      <PopoverContent side="bottom" className="w-auto border-none bg-transparent p-0 shadow-none">
        <EmojiPicker onSelect={() => setOpen(false)} />
      </PopoverContent>
    </Popover>
  )
}
```

### After a pick: the popover closes or stays open

```tsx
import { useState } from "react"
import { SmilePlus } from "lucide-react"
import { EmojiPicker } from "@/components/ui/emoji-picker"
import { IconButton } from "@/components/ui/icon-button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export function Example() {
  const [open, setOpen] = useState(false)
  const [picked, setPicked] = useState<string[]>([])

  return (
    <div className="flex items-center gap-3">
      <Popover open={open} onOpenChange={setOpen}>
        <PopoverTrigger render={<IconButton variant="plain" aria-label="Add a reaction" />}>
          <SmilePlus />
        </PopoverTrigger>
        <PopoverContent side="bottom" className="w-auto border-none bg-transparent p-0 shadow-none">
          <EmojiPicker
            onSelect={(emoji) => {
            setPicked((list) => [...list, emoji])
            setOpen(false)
          }}
          />
        </PopoverContent>
      </Popover>
      <span className="text-sm text-text-secondary">Picked: {picked.join(" ") || "nothing yet"}</span>
    </div>
  )
}
```

## In context

### Message reactions: add a reaction from a smiley button

The smiley button under a message opens the picker. A new emoji joins the reactions, and one that is already there is switched on.

```tsx
import { useState } from "react"
import { SmilePlus } from "lucide-react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { EmojiPicker } from "@/components/ui/emoji-picker"
import { EmojiReactionButton } from "@/components/ui/emoji-reaction-button"
import { IconButton } from "@/components/ui/icon-button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

type Reaction = { emoji: string; count: number; active: boolean }

export function Example() {
  const [open, setOpen] = useState(false)
  const [reactions, setReactions] = useState<Reaction[]>([
    { emoji: "🎉", count: 6, active: true },
    { emoji: "🔥", count: 3, active: false },
  ])

  const toggle = (emoji: string) =>
    setReactions((list) =>
      list
        .map((r) => (r.emoji === emoji ? { ...r, active: !r.active, count: r.count + (r.active ? -1 : 1) } : r))
        .filter((r) => r.count > 0)
    )

  const add = (emoji: string) => {
    setOpen(false)
    const existing = reactions.find((r) => r.emoji === emoji)
    if (!existing) setReactions((list) => [...list, { emoji, count: 1, active: true }])
    else if (!existing.active) toggle(emoji)
  }

  return (
    <div className="flex w-full max-w-md flex-col gap-3 rounded-xl border border-border bg-card p-4">
      <div className="flex items-center gap-2">
        <Avatar size="sm">
          <AvatarFallback>NL</AvatarFallback>
        </Avatar>
        <span className="text-sm font-medium text-foreground">Nora Lindgren</span>
        <span className="text-xs text-text-tertiary">10:42</span>
      </div>
      <p className="text-sm text-text-secondary">Release 2.4 is live for everyone. Thanks for the careful reviews, Daniel and Priya.</p>
      <div className="flex flex-wrap items-center gap-2">
        {reactions.map((r) => (
          <EmojiReactionButton key={r.emoji} emoji={r.emoji} count={r.count} active={r.active} onToggle={() => toggle(r.emoji)} />
        ))}
        <Popover open={open} onOpenChange={setOpen}>
          <PopoverTrigger render={<IconButton variant="plain" size="sm" aria-label="Add a reaction" />}>
            <SmilePlus />
          </PopoverTrigger>
          <PopoverContent side="bottom" align="start" className="w-auto border-none bg-transparent p-0 shadow-none">
            <EmojiPicker onSelect={add} />
          </PopoverContent>
        </Popover>
      </div>
    </div>
  )
}
```

### Comment box: insert an emoji into the text

The picker adds the emoji to the end of the comment and closes. The Post button stays off while the comment is empty.

```tsx
import { useState } from "react"
import { SmilePlus } from "lucide-react"
import { Button } from "@/components/ui/button"
import { EmojiPicker } from "@/components/ui/emoji-picker"
import { IconButton } from "@/components/ui/icon-button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  const [text, setText] = useState("Ship it on Thursday, the checkout fix is verified.")
  const [open, setOpen] = useState(false)

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Textarea aria-label="Comment" value={text} onChange={(event) => setText(event.target.value)} />
      <div className="flex items-center justify-between">
        <Popover open={open} onOpenChange={setOpen}>
          <PopoverTrigger render={<IconButton variant="plain" aria-label="Insert an emoji" />}>
            <SmilePlus />
          </PopoverTrigger>
          <PopoverContent side="bottom" align="start" className="w-auto border-none bg-transparent p-0 shadow-none">
            <EmojiPicker
              onSelect={(emoji) => {
                setText((value) => value + emoji)
                setOpen(false)
              }}
            />
          </PopoverContent>
        </Popover>
        <Button variant="gradient" size="sm" disabled={text.trim() === ""}>
          Post comment
        </Button>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("emoji-picker")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
