← All NIPs

NIP-30

Custom Emoji

DraftEvents

Use your own images as emoji: write :shortcode: in the text and add an emoji tag that maps the shortcode to an image URL. Works in profiles, notes, comments, reactions and statuses.

Status
In use and still allowed to change.
Tags
  • emoji
Last changed
Aug 25, 2026

Try it

Edit the form or the JSON: both stay in sync, the badge says whether the result is valid, and tapping any field explains it.

What to build
Examples
Valid 1 note

Not signed yet · Demo keys only. These personas' secret keys are public on purpose.

Form
Jan 1, 2025, 12:00 AM UTC

Content

Text with :shortcode: placeholders, one per emoji tag.

Tags

  1. emoji Optional

    Defines one custom emoji used in this event.

  2. emoji Optional

    Defines one custom emoji used in this event.

Add tag

How this NIP works

Step 1 of 4

Map a shortcode to an image

Each emoji tag is ["emoji", shortcode, image URL]. The shortcode may only use letters, digits, - and _.

In the course

No course chapter covers this NIP yet. The editor above is the quickest way in.

Used by

See also

Specification

Specification text is quoted in English from the nostr-protocol/nips repository. Our explanations and the interface are translated. Source on GitHub at commit 0046368

Read the spec285 words, quoted from the repository at commit 0046368.

Custom emoji may be added to kind 0, kind 1, kind 1111 (NIP-22), kind 7 (NIP-25) and kind 30315 (NIP-38) events by including one or more "emoji" tags, in the form:

["emoji", <shortcode>, <image-url>, <emoji-set-address>]

Where:

  • <shortcode> is a name given for the emoji, which MUST be comprised of only alphanumeric characters, hyphens, and underscores.
  • <image-url> is a URL to the corresponding image file of the emoji.
  • <emoji-set-address> is an optional address pointer (kind:pubkey:d-tag) to the kind 30030 emoji set (NIP-51) the emoji belongs to.

For each emoji tag, clients should parse emoji shortcodes (aka "emojify") like :shortcode: in the event to display custom emoji.

Clients may allow users to add custom emoji to an event by including :shortcode: identifier in the event, and adding the relevant "emoji" tags.

Kind 0 events

In kind 0 events, the name and about fields should be emojified.

{
  "kind": 0,
  "content": "{\"name\":\"Alex Gleason :soapbox:\"}",
  "tags": [
    ["emoji", "soapbox", "https://gleasonator.com/emoji/Gleasonator/soapbox.png"]
  ],
  "pubkey": "79c2cae114ea28a981e7559b4fe7854a473521a8d22a66bbab9fa248eb820ff6",
  "created_at": 1682790000
}

Kind 1 events

In kind 1 events, the content should be emojified.

{
  "kind": 1,
  "content": "Hello :gleasonator: 😂 :ablobcatrainbow: :disputed: yolo",
  "tags": [
    ["emoji", "ablobcatrainbow", "https://gleasonator.com/emoji/blobcat/ablobcatrainbow.png", "30030:79c2cae114ea28a981e7559b4fe7854a473521a8d22a66bbab9fa248eb820ff6:blobcats"],
    ["emoji", "disputed", "https://gleasonator.com/emoji/Fun/disputed.png"],
    ["emoji", "gleasonator", "https://gleasonator.com/emoji/Gleasonator/gleasonator.png"]
  ],
  "pubkey": "79c2cae114ea28a981e7559b4fe7854a473521a8d22a66bbab9fa248eb820ff6",
  "created_at": 1682630000
}

Kind 1111 events

In kind 1111 events, the content should be emojified.

{
  "kind": 1111,
  "content": "Let's party! :hyves_banaan:",
  "tags": [
    ["emoji", "hyves_banaan", "https://relay.nyves.nl/8408b236b11fe5c764d139d37e670d5207b3825fe6396392799b02c4e6bd2ebf.gif", "30030:9919981db5d9f59713bd717069212c32a19b55f2280a51e70c49c5b73da306b9:Hyves"]
  ],
  "pubkey": "79c2cae114ea28a981e7559b4fe7854a473521a8d22a66bbab9fa248eb820ff6",
  "created_at": 1682630000
}

Kind 7 events

In kind 7 events, the content should be emojified.

{
  "kind": 7,
  "content": ":dezh:",
  "tags": [
    ["emoji", "dezh", "https://raw.githubusercontent.com/dezh-tech/brand-assets/main/dezh/logo/black-normal.svg"]
  ],
  "pubkey": "79c2cae114ea28a981e7559b4fe7854a473521a8d22a66bbab9fa248eb820ff6",
  "created_at": 1682630000
}