NIP-30: Custom Emoji
Culture needs tiny images too
NIP-30 is the custom emoji standard. It looks playful, but it solves a real interoperability problem. Communities build identity through little images, inside jokes, logos, badges, reaction faces and local symbols. If each client encodes those differently, the same note becomes expressive in one app and broken text in another.
The NIP defines an emoji tag that maps a shortcode to an image URL. When a user writes :soapbox: in supported content, a client can render the image linked by the matching tag. The event remains readable as text, while clients that support custom emoji can make it visual.
This matters beyond jokes. Custom emoji appear in profile names, bios, notes, reactions and user statuses. They connect to NIP-25 reactions and NIP-38 statuses, and they can belong to NIP-51 emoji sets. The feature is small, social and surprisingly structural.
Shortcodes, image URLs and optional emoji-set addresses
The tag format is ["emoji", shortcode, image-url, emoji-set-address]. The shortcode contains alphanumeric characters, hyphens and underscores. The image URL points at the emoji file. The optional emoji-set address points at a kind 30030 emoji set using a kind:pubkey:d-tag coordinate.
NIP-30 applies to kind 0 metadata, kind 1 text notes, kind 7 reactions and kind 30315 user statuses. In kind 0 events, clients can emojify profile name and about. In kind 1, they emojify content. In kind 7, the custom emoji can be the whole reaction value.
The standard does not magically bundle image files into Nostr. It gives a signed event a clear mapping from text shortcode to external media URL. That means rendering depends on image availability, safe loading and client policy.
From custom emoji to emoji sets
Alex Gleason added NIP-30 in April 2023. Jiftechnify soon allowed underscores in shortcodes. In November 2023, author metadata was removed across NIPs. Asai Toshiya added the list of supported kinds in January 2024.
In September 2024, Zig Blathazar connected custom emoji to reactions. In March 2026, Alejandro Gomez added the optional emoji-set address to emoji tags, and Alex Gleason updated shortcode rules to include hyphens. These changes show the standard moving from one-off inline images toward reusable emoji collections.
The connection to kind 30030 matters because communities rarely manage emoji one at a time. Sets let a group, creator or app publish a collection and let clients preserve provenance instead of copying isolated URLs forever.
Rendering emoji means parsing text and trusting media carefully
NIP-30 appears in several implementation surfaces. Nostr Compass explains custom emoji as shortcode references resolved through emoji tags. Nostrbook's kind 30030 page describes emoji sets and their relationship to the NIP-30 tag format. The Nostr Lib metadata module lists NIP-30 alongside profile metadata support. nostr-sdk-ios tracked NIP-30 implementation in issue #103. 0xChat's Dart library lists NIP-30 support.
A client implementation has to scan supported fields for :shortcode: tokens, match them to emoji tags, avoid rendering missing or duplicate mappings unpredictably, load images safely and keep fallback text visible. It also has to decide how big emoji render in names, notes and reactions, because a profile name and a timeline note are different surfaces.
Custom emoji also intersects with moderation. Image URLs can be broken, offensive, huge, tracking-heavy or unsafe. A client can support NIP-30 and still proxy images, cache them, hide remote media by default or restrict which emoji sets render automatically.
Tiny images still carry trust decisions
The first risk is media trust. A custom emoji is an external image. It can disappear, change, track requests or contain material a client does not want to render. Responsible clients treat emoji images like any other remote media.
The second risk is namespace confusion. Two events can define the same shortcode with different images. A single event's tags decide its own rendering, but users may still expect a shortcode to mean the same thing across a community. Emoji sets help, but they do not remove the need for clear UI around provenance and overrides.
Read NIP-30 in the wild
NIP-30 gives custom emoji a portable form. Communities can develop visual language without every client hard-coding the same sticker set.
The danger is broken meaning. If the image disappears, the shortcode collides or the emoji source is untrusted, the post loses part of its tone. Treat emoji as small media objects with provenance, not just decoration.
What changes when you actually use it
For you, NIP-30: Custom Emoji is felt when a post becomes a durable object: article, file, image, video, audio, bookmark, wiki entry or source reference. The question is whether the work still makes sense after one app, host or relay disappears. The concrete pieces kind 0, kind 1, kind 7, kind 30315, kind 30030, draft decide whether the object carries enough context to survive.
What changes for builders and operators
For builders, NIP-30: Custom Emoji is context preservation. Store enough title, tag, author, hash, URL, media, preview and reference material that another interface can rebuild the object. If your feature depends on a private database to make sense, the NIP is not doing the portability work yet.
What the official file makes concrete
The official file is organized around Kind 0 events, Kind 1 events, Kind 7 events. Inspect kind 0, kind 1, kind 7, kind 30315, kind 30030, draft, kind:pubkey:d-tag, name because these are the pieces most likely to surface as product behavior. Read it beside NIP-25, NIP-38, NIP-51 before treating it as isolated.
NIP-30: Custom Emoji protects context. Titles, media, hashes, source links, timestamps and references decide whether work survives beyond one app.
Where it breaks
The failure mode in NIP-30: Custom Emoji is link rot with a nice interface. Media disappears, metadata lies, source URLs change, hashes are missing or an article loses its addressable identity. The page needs to make durability part of the feature, not an afterthought.
Where this appears outside the markdown
In the ecosystem, NIP-30: Custom Emoji is part of the creator and archive layer. It decides whether writing, media, files, bookmarks, wiki material or source references remain understandable after the first app disappears. That is why media standards need to talk about storage, provenance and recovery, not only presentation.
The nearby-standard trap
The nearby-standard trap in NIP-30: Custom Emoji is flattening every creative object into a note with a link. Articles, videos, files, torrents, highlights, images, wiki entries and bookmarks carry different metadata and storage pressure. Read NIP-25, NIP-38, NIP-51 so the product does not throw away the part that made the object portable.
Language that keeps the feature honest
Good product copy for NIP-30: Custom Emoji names the object and the storage. It says article, file, image, video, bookmark, wiki page, torrent, highlight or podcast episode, then tells you where the signed metadata ends and where external hosting begins.
What this page does not promise
NIP-30: Custom Emoji does not guarantee that published work survives forever. It can carry richer metadata, hashes, references or addressability, but files still need hosts, relays still need retention, and clients still need to render the object faithfully. Treat the NIP as the signed map of the work, then check where the actual bytes, previews and source links live.
Read it as a field test
Start NIP-30: Custom Emoji with the object you want to keep: article, file, media, bookmark, repository, torrent, wiki entry or podcast episode. Then trace which parts are signed, which parts are hosted, and which parts another client can reconstruct from kind 0, kind 1, kind 7, kind 30315, kind 30030, draft. That is the difference between portable publishing and a pretty link preview.
Where the standard earns trust
The source links give you places to test the interpretation in public: nips.nostr.com NIP-30 mirror, NIP-25 Reactions, NIP-51 Lists, Nostr Compass NIP-30. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-30 source is the anchor for exact wording, and NIP-30 commit history shows how that wording moved over time. The strongest secondary clues here are nips.nostr.com NIP-30 mirror, NIP-25 Reactions, NIP-51 Lists. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-30: Custom Emoji: first the human promise, then kind 0, kind 1, kind 7, kind 30315, kind 30030, draft, then the implementation record, then the real-world failure case. That order keeps NIP-30 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Where do the signed metadata and the actual media or file bytes part ways?
- Can the object still be identified by hash, address, title, author and source if the first URL breaks?
- Does a second client know enough from
kind 0,kind 1,kind 7,kind 30315to render the work without private context?
What to verify before you rely on it
- Find
kind 0,kind 1,kind 7,kind 30315,kind 30030in the official file and check where the UI exposes the same concept. - Read NIP-25, NIP-38, NIP-51 as context before treating NIP-30 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-30: Custom Emoji in that order: Official NIP-30 source for the current wording; NIP-30 commit history for the change record; nips.nostr.com NIP-30 mirror, NIP-25 Reactions, NIP-51 Lists for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
