# Custom Emojis Extension

Adds custom emojis to any entity with text content.

Extension name: `pub.versia:custom_emojis`

The Custom Emojis extension lets an entity carry its own emoji images, so that a name such as `:happy_face:` in its text can be shown as an image.

## Definition

### CustomEmoji

**Fields**

- `name` (`string`, required): Emoji name, surrounded by identification characters (for example, colons: `:happy_face:`).

  The following characters are allowed:

  - `a-z`
  - `A-Z`
  - `0-9`
  - `_`, `-`

  Identification characters **MUST NOT** be any of the characters allowed above. A name **MUST** have exactly two identification characters, one at the beginning and one at the end.

- `content` (`Media`, required): Emoji image. **MUST** be an image (`image/*`).

```jsonc title="Example Emoji"
{
    "name": ":happy_face:",
    "content": {
        "url": "https://cdn.example.com/emojis/happy_face.webp",
        "media_type": "image/webp",
        "description": "A happy emoji smiling."
    }
}
```

### Extension

Custom Emojis can be added to any entity with text content. The extension name is `pub.versia:custom_emojis`.

- Extension ID: `pub.versia:custom_emojis`

**Fields**

- `emojis` (`CustomEmoji[]`, required): [Custom emojis](/extensions/custom-emojis#custom-emoji) used in the entity.

```jsonc title="Example Usage"
{
    "id": "033mcbcsyt000",
    "type": "pub.versia:social/Note",
    "created_at": "2024-04-09T01:38:51Z",
    "content": "<p>Hello, world :happy_face:!</p>",
    "visibility": "public",
    // ...
    "extensions": {
        "pub.versia:custom_emojis": {
            "emojis": [
                {
                    "name": ":happy_face:",
                    "content": {
                        "url": "https://cdn.example.com/emojis/happy_face.webp",
                        "media_type": "image/webp",
                        "description": "A happy emoji smiling."
                    }
                }
            ]
        }
    }
}
```

## Behavior

To render custom emojis, clients **SHOULD** perform the following steps:

1. Find all instances of custom emoji names in the text content. In [RichText](/structures/rich-text), names are only found in text, not inside attribute values.
2. Replace the custom emoji names with the corresponding emoji images in text.

If custom emojis are not supported, clients **SHOULD** leave the custom emoji names as-is. Images **SHOULD** have any associated `alt` text for accessibility.

```html title="Example HTML/CSS"
<style>
img.emoji {
    display: inline;
    height: 1em;
}
</style>

<p>
    Hello, world <img src="https://cdn.example.com/emojis/happy_face.webp" alt="A happy emoji smiling." class="emoji" />!
</p>
```

Emojis **SHOULD** be displayed at a fixed height (such as `1em`), but their width **SHOULD** be allowed to be flexible.