# Custom Emojis

Source: https://docs.gryt.chat/docs/use/emojis

Upload, manage, and import custom emojis for your Gryt server

Custom emojis let members express themselves with images unique to your server. Anyone can use them in chat with the `:shortcode:` syntax, and admins can manage the full library from Server Settings.

## Supported formats

| Format | Extension | Animated | Stored as |
|--------|-----------|----------|-----------|
| PNG | `.png` | No | AVIF |
| JPEG | `.jpg` / `.jpeg` | No | AVIF |
| WebP | `.webp` | Yes | Animated WebP, animation kept |
| GIF | `.gif` | Yes | Animated WebP, animation kept |
| AVIF | `.avif` | Yes | Animated WebP if animated, AVIF if not |

Everything is resized to **128 pixels tall**, keeping the aspect ratio and never enlarging something smaller. A still image comes back out as AVIF and an animated one as animated WebP, whatever it arrived as.

**SVG isn't accepted.** An SVG is a document rather than a picture. It can carry a `<script>`, and a browser asked to open one from your server's own origin will run it. Uploading one gets "SVG images are not accepted".

The size limit per image is a per-server setting, `emojiMaxBytes`. It defaults to **100 MB** and can be set anywhere from 64 KB to 200 MB. Anything bigger is refused.

## Naming rules

Emoji shortcodes must follow these rules:

- **2 to 32 characters** long
- Only **letters**, **numbers**, and **underscores** (`A-Z`, `a-z`, `0-9`, `_`)
- Must be unique within the server

Examples: `:pepehappy:`, `:cat_jam:`, `:lol2:`

## Uploading emojis

Go to **Server Settings > Emojis** (requires admin or owner role).

### Single or multi-file upload

1. Click **Choose files** and select one or more images.
2. Each file appears in a preview list with an auto-generated name derived from the filename.
3. Edit the shortcode name for any emoji before uploading.
4. Click **Upload all** to upload the entire batch, or click the upload icon on an individual emoji.

### ZIP archive upload

You can upload a `.zip` file containing multiple images:

1. Click **Choose files** and select a `.zip` archive.
2. Gryt extracts all valid image files from the archive (nested folders are supported; `__MACOSX` metadata is ignored).
3. Each extracted image appears in the preview list with its filename used as the shortcode.
4. Edit names as needed, then upload.

Files inside the ZIP follow the same format and size rules as individual uploads.

## Importing from BetterTTV or emoji.gg

One box takes a link and works out where it is from. In **Server Settings > Emojis**, under **Import from a link**, paste any of these:

| Link | What you get |
|------|--------------|
| `betterttv.com/users/<id>` | That user's channel emotes and shared emotes |
| `betterttv.com/emotes/<id>` | The one emote |
| `emoji.gg/user/<name>` | That profile's emojis |
| `emoji.gg/pack/<slug>` | The pack |
| `emoji.gg/emoji/<slug>` | The one emoji |

### Step by step

1. Open **Server Settings > Emojis**.
2. Paste the link and click **Fetch**.
3. A preview grid appears. Each emote shows a thumbnail, an editable shortcode derived from its name, and a **GIF** badge if it's animated.
4. Tick the ones you want, or use **Select all** and **Deselect all**. The filter field narrows a long list.
5. Rename anything you like. Names that clash with an emoji already on the server are flagged.
6. Click **Import N emojis**.

The server fetches each one at full resolution and puts it through the same pipeline as an upload, so the format rules above apply here too.

A large emoji.gg profile is read a fixed number of pages deep. When that happens the list says so, rather than handing you a short list that looks complete.

## Using emojis in chat

Type `:` followed by the shortcode to trigger the autocomplete picker. You can also open the emoji picker from the chat input toolbar.

Custom emojis appear alongside standard Unicode emojis in the picker, in a dedicated **Custom** category.

```
:pepehappy:     → shows the custom emoji
:wave:          → shows the standard Unicode wave emoji
```

## Managing existing emojis

In **Server Settings > Emojis**, below the upload section, you'll see the full list of server emojis. Admins can:

- **Rename** — Click the edit icon next to any emoji to change its shortcode.
- **Delete** — Click the delete icon to permanently remove an emoji from the server.

Renaming an emoji updates the shortcode everywhere going forward; messages already sent will reference the old name and may show as missing.