> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeonbot.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Reaction Roles

> Allow users to self-assign roles by reacting to messages with specific emojis.

The Reaction Role system allows you to create interactive panels where server members can click on emojis beneath a message to automatically receive or remove roles.

ZEON's reaction role engine supports multiple assignment modes (like unique selections or reverse roles) and allows up to **20 reaction roles per message**.

<Note>
  **Required Permission:** [Server Owner](/permissions/hierarchy), [Extra Owners](/permissions/extra-owners), and [Admin Access](/permissions/admin-access) can manage reaction roles.
</Note>

***

## Basic Setup

### 1. Add a Reaction Role

To add a single reaction role to a message, use the `add` command. You can provide either the Message ID or the direct Message Link.

```bash theme={null}
.reactionrole add <message> <emoji> <role>
```

### 2. Add Multiple Reaction Roles (Bulk)

If you want to set up an entire panel at once, use `addmany`. You must provide exact pairs of emojis and role mentions (or Role IDs).

```bash theme={null}
.reactionrole addmany <message> :emoji1: @role1 :emoji2: @role2
```

<Tip>
  When using custom emojis, make sure ZEON is in the server where the emoji originates, or it won't be able to react to the message!
</Tip>

***

## Panel Modes (Format)

You can change how a reaction role panel behaves using the `format` command. This allows you to create distinct types of role panels, like color selectors or verification buttons.

```bash theme={null}
.reactionrole format <message> <mode>
```

| Mode      | Behavior                                                                                                                                                 |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `normal`  | **(Default)** React to receive the role. Remove the reaction to lose the role.                                                                           |
| `unique`  | Users can only claim **one** role from this panel. Reacting to a new emoji automatically removes the previous role. Great for Color or Region selectors. |
| `verify`  | React to receive the role. Removing the reaction does **not** remove the role. Perfect for server verification or rule acceptance gates.                 |
| `reverse` | React to **lose** the role. Remove the reaction to receive the role. Useful for opt-out ping roles.                                                      |

### Maximum Roles Limit

If you want to allow users to pick multiple roles but still restrict them to a specific amount (e.g., "Pick up to 3 game roles"), use the `maxroles` command:

```bash theme={null}
.reactionrole maxroles <message> <count>
```

*(Set `<count>` to `0` to allow unlimited roles).*

***

## Management Commands

Once a panel is set up, you can edit, clone, or completely wipe it using the following commands:

| Command                                       | Description                                                            |
| :-------------------------------------------- | :--------------------------------------------------------------------- |
| `.reactionrole remove <message> <emoji>`      | Removes a specific emoji/role pair from the panel.                     |
| `.reactionrole edit <message> <emoji> <role>` | Changes the role assigned to an existing emoji on the panel.           |
| `.reactionrole clone <source> <target>`       | Copies an entire reaction role setup from one message to another.      |
| `.reactionrole clear <message>`               | Wipes all reaction roles from the specified message.                   |
| `.reactionrole show`                          | Displays a dashboard of all active reaction role panels in the server. |

***

## Security Restrictions

To protect your server from privilege escalation attacks, ZEON enforces strict security checks when creating reaction roles:

1. **Hierarchy Guard:** You cannot assign a role that is higher than or equal to your own top role (unless you are the Server Owner).
2. **Bot Hierarchy:** The bot cannot assign roles that are higher than its own top role.
3. **Dangerous Permissions Guard:** ZEON will explicitly block any attempt to create a reaction role for a role that contains dangerous permissions (e.g., Administrator, Manage Server, Ban Members). This ensures no one can accidentally create a backdoor into your server.