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

# Self-assignable roles

> Let members pick their own roles with reactions, buttons or a dropdown menu.

Three ways to do the same thing. Buttons are the modern default; dropdowns are best when there are a lot of options; reactions are the classic approach and still work fine.

All require **Manage Roles**, and mira's role must sit **above** every role being handed out.

<Steps>
  <Step title="Post the message first">
    Whatever the members will click on. Use `!embed` if you want it to look designed:

    ```javascript theme={null}
    !embed {title: Pick your roles} {description: React below to get notified about the things you care about.} {color: #5cacec}
    ```
  </Step>

  <Step title="Attach roles to it">
    Every command below takes that message — as a link, an ID, or a reply.
  </Step>
</Steps>

## Button roles

The best default. Clear, mobile-friendly, and clicking toggles the role.

<CodeGroup>
  ```javascript Add a button theme={null}
  !buttonrole add <message> @Announcements
  ```

  ```javascript With styling theme={null}
  !buttonrole add <message> @Announcements success 📢 "Announcements"
  ```

  ```javascript Remove one theme={null}
  !buttonrole remove <message> @Announcements
  ```

  ```javascript Remove all from a message theme={null}
  !buttonrole clear <message>
  ```

  ```javascript See everything theme={null}
  !buttonrole list
  ```
</CodeGroup>

Arguments after the role are optional and positional: **style**, **emoji**, **label**.

| Style       | Colour  |
| ----------- | ------- |
| `primary`   | Blurple |
| `secondary` | Grey    |
| `success`   | Green   |
| `danger`    | Red     |

If a message gets edited by something else and loses its buttons:

```javascript theme={null}
!buttonrole render <message>
```

Aliases: `buttonroles`, `btr`. `render` aliases: `refresh`, `sync`.

## Dropdown roles

Better past about five roles — one compact menu instead of a wall of buttons.

<CodeGroup>
  ```javascript Add an option theme={null}
  !dropdownrole add <message> @Announcements 📢 "Announcements"
  ```

  ```javascript Describe an option theme={null}
  !dropdownrole description <message> @Announcements "Get pinged for news"
  ```

  ```javascript Set the placeholder theme={null}
  !dropdownrole placeholder <message> "Choose your roles..."
  ```

  ```javascript Remove an option theme={null}
  !dropdownrole remove <message> @Announcements
  ```

  ```javascript See everything theme={null}
  !dropdownrole list
  ```
</CodeGroup>

Members can select multiple options, and deselecting removes the role. Aliases: `dropdownroles`, `selectrole`, `dropdown`, `dd`.

<Info>
  Discord caps a dropdown at **25 options**. Past that, use a second message.
</Info>

## Reaction roles

<CodeGroup>
  ```javascript Add theme={null}
  !reactionrole add <message> 📢 @Announcements
  ```

  ```javascript Remove theme={null}
  !reactionrole remove <message> 📢
  ```

  ```javascript Clear a message theme={null}
  !reactionrole clear <message>
  ```

  ```javascript List theme={null}
  !reactionrole list
  ```
</CodeGroup>

Aliases: `reactionroles`, `rr`.

### Limiting picks

```javascript theme={null}
!reactionrole limit <message> 1
```

Caps how many roles a member can take from that message. Set to `1` for mutually exclusive choices — picking a new one removes the old.

### Inverting

```javascript theme={null}
!reactionrole reverse <message> on
```

Reacting **removes** the role instead of granting it. Useful for opt-outs: "react to stop being pinged for events".

### Fixing desyncs

```javascript theme={null}
!reactionrole sync <message>
```

Discord occasionally drops reaction events during outages, leaving people with a reaction but no role. This walks the reactions and fixes every mismatch. Aliases: `fix`, `refresh`.

## Which should I use?

<AccordionGroup>
  <Accordion title="Under 5 roles" icon="hand-pointer">
    **Buttons.** One click, visible without interacting, works well on mobile.
  </Accordion>

  <Accordion title="5–25 roles" icon="list">
    **Dropdown.** Keeps the message short and supports per-option descriptions, which matters when the role names aren't self-explanatory.
  </Accordion>

  <Accordion title="Over 25 roles" icon="table-cells">
    **Multiple messages**, one per category — colours, pings, games. A dropdown each, or buttons if each category is small.
  </Accordion>

  <Accordion title="Aesthetic reasons" icon="star">
    **Reactions.** Some people prefer how they look, and they're the only option that works on very old messages you can't edit. They're also the least reliable — reaction events get dropped, which is what `reactionrole sync` exists for.
  </Accordion>
</AccordionGroup>

<Tip>
  Nothing stops you mixing them. Buttons and a dropdown on the same message both work — `dropdownrole render` re-applies the dropdown *and* any button roles on that message.
</Tip>

## A worked example

```javascript theme={null}
// 1. post the message
!embed {title: Roles} {description: **Notifications** — pick what you want pinged for.
**Colours** — one at a time.} {color: dominant}

// 2. notification roles as a dropdown
!dropdownrole placeholder <message> "Notifications..."
!dropdownrole add <message> @Announcements 📢 "Announcements"
!dropdownrole add <message> @Events 🎉 "Events"
!dropdownrole add <message> @Giveaways 🎁 "Giveaways"
!dropdownrole description <message> @Announcements "Server news and updates"

// 3. colours as buttons on a second message
!buttonrole add <message2> @Pink secondary 🌸
!buttonrole add <message2> @Blue secondary 💙
!buttonrole add <message2> @Green secondary 💚
```

## Command reference

| Command                                                   | Permission   | Description                    |
| --------------------------------------------------------- | ------------ | ------------------------------ |
| `buttonrole add <message> <role> [style] [emoji] [label]` | Manage Roles | Add a button                   |
| `buttonrole remove <message> [role]`                      | Manage Roles | Remove a button                |
| `buttonrole clear [message]`                              | Manage Roles | Clear a message, or the server |
| `buttonrole list`                                         | Manage Roles | View all button roles          |
| `buttonrole render [message]`                             | Manage Roles | Re-apply components            |
| `dropdownrole add <message> <role> [emoji] [label]`       | Manage Roles | Add an option                  |
| `dropdownrole description <message> <role> [text]`        | Manage Roles | Describe an option             |
| `dropdownrole placeholder <message> <text>`               | Manage Roles | Set placeholder text           |
| `dropdownrole remove <message> [role]`                    | Manage Roles | Remove an option               |
| `dropdownrole clear [message]`                            | Manage Roles | Clear a message, or the server |
| `dropdownrole list`                                       | Manage Roles | View all dropdown roles        |
| `dropdownrole render [message]`                           | Manage Roles | Re-apply the dropdown          |
| `reactionrole add <message> <emoji> <role>`               | Manage Roles | Add a reaction role            |
| `reactionrole remove <message> <emoji>`                   | Manage Roles | Remove one                     |
| `reactionrole clear <message>`                            | Manage Roles | Clear a message                |
| `reactionrole limit <message> <amount>`                   | Manage Roles | Cap roles per member           |
| `reactionrole reverse <message> (on/off)`                 | Manage Roles | Invert the behaviour           |
| `reactionrole sync <message>`                             | Manage Roles | Fix mismatches                 |
| `reactionrole list`                                       | Manage Roles | View all reaction roles        |