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

# Booster Role

> Give server boosters custom roles with personalized colors, names, and icons

## Overview

Booster roles allow server boosters to create and customize their own personal roles with custom colors, names, and icons. Boosters can also share their roles with other members, creating a unique reward system for your most dedicated supporters.

<Info>
  Server administrators must set a base role before boosters can create their roles. The bot needs proper role hierarchy permissions to manage booster roles.
</Info>

***

## For Boosters

### Creating & Managing Your Role

<AccordionGroup>
  <Accordion title="br create" icon="plus">
    Create your custom booster role with optional colors.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br create <name>
      ~br create <color> <name>
      ~br create <color1> <color2> <name>
      ```

      ```bash Examples theme={null}
      ~br create My Cool Role
      ~br create #FF0000 Red Role
      ~br create crimson Crimson Role
      ~br create red blue Gradient Role
      ```
    </CodeGroup>

    **Parameters:**

    * **name** — Your role name (100 characters max)
    * **color** (optional) — Hex code or color name
    * **color2** (optional) — Second color for gradient (requires server boost level)

    **Supported Colors:**

    * Hex codes: `#FF0000`, `#00FF00`, `#0099FF`
    * Color names: `red`, `blue`, `green`, `purple`, `pink`, `orange`, `yellow`, `crimson`, `gold`, `cyan`, `magenta`, and [50+ more](/booster-role#color-reference)

    <Note>
      You must be a server booster or have the configured base role to create a booster role.
    </Note>
  </Accordion>

  <Accordion title="br color" icon="palette">
    Change your booster role's color.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br color <hex/color name>
      ~br colour <hex/color name>
      ```

      ```bash Examples theme={null}
      ~br color #FF0000
      ~br color crimson
      ~br colour blue
      ```
    </CodeGroup>

    **Examples:**

    * `~br color #5865F2` — Discord blurple
    * `~br color gold` — Gold color
    * `~br color #FF69B4` — Hot pink
  </Accordion>

  <Accordion title="br name" icon="pen">
    Rename your booster role.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br name <new name>
      ~br rename <new name>
      ```

      ```bash Examples theme={null}
      ~br name Super Cool Role
      ~br rename Epic Booster
      ```
    </CodeGroup>

    **Cooldown:** 60 seconds between renames

    **Limits:** 100 characters maximum
  </Accordion>

  <Accordion title="br icon" icon="image">
    Set a custom icon for your role (requires Level 2 boost).

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br icon <emoji/url>
      ```

      ```bash Examples theme={null}
      ~br icon 🔥
      ~br icon <:custom:1234567890>
      ~br icon https://example.com/icon.png
      ```
    </CodeGroup>

    **Supported:**

    * Unicode emojis: 🔥 ⭐ 💎
    * Custom Discord emojis
    * Direct image URLs (PNG, JPG, GIF)

    <Warning>
      Role icons require the server to be boosted to Level 2 or higher.
    </Warning>
  </Accordion>

  <Accordion title="br remove" icon="trash">
    Delete your booster role.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br remove
      ~br delete
      ```

      ```bash Example theme={null}
      ~br remove
      ```
    </CodeGroup>

    <Warning>
      This action is permanent and cannot be undone. The role will be completely deleted from the server.
    </Warning>
  </Accordion>
</AccordionGroup>

***

### Quick Color Options

<AccordionGroup>
  <Accordion title="br dominant" icon="eye-dropper">
    Set your role color to match your avatar's dominant color.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br dominant
      ```

      ```bash Example theme={null}
      ~br dominant
      ```
    </CodeGroup>

    **What It Does:**

    * Analyzes your current avatar
    * Extracts the dominant color
    * Applies it to your booster role
  </Accordion>

  <Accordion title="br random" icon="shuffle">
    Set a completely random color for your role.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br random
      ```

      ```bash Example theme={null}
      ~br random
      ```
    </CodeGroup>

    **Perfect For:**

    * Quick color changes
    * Experimenting with different looks
    * Surprising yourself with new colors
  </Accordion>
</AccordionGroup>

***

### Sharing Your Role

<AccordionGroup>
  <Accordion title="br share" icon="share-nodes">
    Share your booster role with another member.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br share <user>
      ```

      ```bash Examples theme={null}
      ~br share @username
      ~br share 123456789012345678
      ~br share username
      ```
    </CodeGroup>

    **How It Works:**

    1. You send a share request
    2. Target user gets an Accept/Decline prompt
    3. If accepted, they receive your role
    4. They can remove it anytime with `br share remove`

    **Cooldown:** 2 seconds between shares

    <Note>
      The target user must accept the request within 30 seconds.
    </Note>
  </Accordion>

  <Accordion title="br share list" icon="list">
    See who has access to your booster role.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br share list
      ```

      ```bash Example theme={null}
      ~br share list
      ```
    </CodeGroup>

    Shows all members who are currently sharing your booster role.
  </Accordion>

  <Accordion title="br share remove" icon="user-minus">
    Remove yourself from a shared booster role.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br share remove <role>
      ```

      ```bash Examples theme={null}
      ~br share remove @role
      ~br share remove 987654321098765432
      ~br share remove Role Name
      ```
    </CodeGroup>

    **Use This To:**

    * Leave a shared role you no longer want
    * Free up a slot for other shared roles
    * Clean up your role list
  </Accordion>
</AccordionGroup>

***

## For Administrators

### Server Configuration

<AccordionGroup>
  <Accordion title="br base" icon="layer-group">
    Set the base role that determines where booster roles are positioned.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br base <role>
      ```

      ```bash Examples theme={null}
      ~br base @Booster
      ~br base 123456789012345678
      ~br base Server Booster
      ```
    </CodeGroup>

    **Important:**

    * All new booster roles will be placed directly under this role
    * This role must be above where you want booster roles
    * Bot's role must be above this base role
    * **Required** before boosters can create roles

    **Permissions:** Administrator
  </Accordion>

  <Accordion title="br limit" icon="hashtag">
    Set maximum number of booster roles each user can create.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br limit <number>
      ```

      ```bash Examples theme={null}
      ~br limit 1
      ~br limit 3
      ~br limit 5
      ```
    </CodeGroup>

    **Typical Settings:**

    * `1` — One role per booster (most common)
    * `2-3` — Multiple roles for customization
    * `5+` — Very generous servers

    **Permissions:** Administrator
  </Accordion>

  <Accordion title="br share max" icon="users">
    Set maximum members who can share a single booster role.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br share max <number>
      ```

      ```bash Examples theme={null}
      ~br share max 5
      ~br share max 10
      ~br share max 20
      ```
    </CodeGroup>

    **Purpose:**

    * Prevents one role from being shared with too many people
    * Keeps booster roles feeling exclusive
    * Manages server role count

    **Permissions:** Administrator
  </Accordion>

  <Accordion title="br share limit" icon="user-group">
    Set maximum shared roles each member can have.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br share limit <number>
      ```

      ```bash Examples theme={null}
      ~br share limit 3
      ~br share limit 5
      ~br share limit 10
      ```
    </CodeGroup>

    **Purpose:**

    * Prevents members from collecting too many shared roles
    * Keeps role lists manageable
    * Balances role distribution

    **Permissions:** Administrator
  </Accordion>

  <Accordion title="br list" icon="rectangle-list">
    View all booster roles in the server.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br list
      ```

      ```bash Example theme={null}
      ~br list
      ```
    </CodeGroup>

    **Shows:**

    * All booster roles
    * Role owners
    * Numbered list for easy reference

    **Useful For:**

    * Auditing booster roles
    * Finding specific roles
    * Managing server roles

    **Permissions:** Administrator
  </Accordion>

  <Accordion title="br link" icon="link">
    Link an existing role as a booster role for a member.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~br link <member> <role>
      ```

      ```bash Examples theme={null}
      ~br link @user @role
      ~br link username Existing Role
      ~br link 123456789 987654321
      ```
    </CodeGroup>

    **Use Cases:**

    * Migrate existing custom roles to booster system
    * Reward specific boosters with pre-made roles
    * Import roles from other systems

    **Requirements:**

    * Member must be a server booster
    * Role cannot already be a booster role

    **Permissions:** Administrator
  </Accordion>
</AccordionGroup>

***

## Color Reference

<Tabs>
  <Tab title="Basic Colors">
    | Color Name | Hex Code | Preview |
    | ---------- | -------- | ------- |
    | red        | #ff0000  | 🔴      |
    | blue       | #0000ff  | 🔵      |
    | green      | #00ff00  | 🟢      |
    | yellow     | #ffff00  | 🟡      |
    | purple     | #800080  | 🟣      |
    | pink       | #ff69b4  | 🩷      |
    | orange     | #ffa500  | 🟠      |
    | black      | #000000  | ⚫       |
    | white      | #ffffff  | ⚪       |
    | gray       | #808080  | ⚪       |
  </Tab>

  <Tab title="Vibrant Colors">
    | Color Name | Hex Code |
    | ---------- | -------- |
    | crimson    | #dc143c  |
    | gold       | #ffd700  |
    | lime       | #32cd32  |
    | cyan       | #00ffff  |
    | magenta    | #ff00ff  |
    | coral      | #ff7f50  |
    | turquoise  | #40e0d0  |
    | violet     | #ee82ee  |
    | indigo     | #4b0082  |
    | lavender   | #e6e6fa  |
  </Tab>

  <Tab title="Dark Colors">
    | Color Name  | Hex Code |
    | ----------- | -------- |
    | darkred     | #8b0000  |
    | darkblue    | #00008b  |
    | darkgreen   | #006400  |
    | darkorange  | #ff8c00  |
    | darkmagenta | #8b008b  |
    | darkcyan    | #008b8b  |
    | navy        | #000080  |
    | maroon      | #800000  |
    | olive       | #808000  |
    | teal        | #008080  |
  </Tab>

  <Tab title="Light Colors">
    | Color Name   | Hex Code |
    | ------------ | -------- |
    | lightblue    | #add8e6  |
    | lightgreen   | #90ee90  |
    | lightcoral   | #f08080  |
    | lightcyan    | #e0ffff  |
    | lightyellow  | #ffffe0  |
    | lightskyblue | #87cefa  |
    | silver       | #c0c0c0  |
    | beige        | #f5f5dc  |
    | wheat        | #f5deb3  |
    | ivory        | #fffff0  |
  </Tab>
</Tabs>

***

## Permission Requirements

<CardGroup cols={2}>
  <Card title="For Boosters" icon="rocket">
    **Requirements:**

    * Server Booster status OR configured base role
    * No special Discord permissions needed

    **Note:** Admins can use all commands regardless of booster status
  </Card>

  <Card title="For Administrators" icon="shield">
    **Requirements:**

    * Administrator permission

    **Commands:**

    * `br base`, `br limit`, `br list`
    * `br share max`, `br share limit`
    * `br link`
  </Card>
</CardGroup>

***

## Bot Permissions

The bot needs these permissions to manage booster roles:

<CardGroup cols={3}>
  <Card title="Manage Roles" icon="key">
    Required to create, edit, and delete booster roles
  </Card>

  <Card title="Role Hierarchy" icon="layer-group">
    Bot's role must be above the base role and all booster roles
  </Card>

  <Card title="View Channels" icon="eye">
    Required to respond to commands
  </Card>
</CardGroup>

***

## Setup Guide

<Steps>
  <Step title="Invite the Bot">
    Make sure the bot is invited with Manage Roles permission
  </Step>

  <Step title="Position Bot Role">
    Drag the bot's role above where you want booster roles to appear
  </Step>

  <Step title="Create Base Role">
    Create a role (e.g., "Server Booster") and position it where booster roles should appear
  </Step>

  <Step title="Set Base Role">
    ```bash theme={null}
    ~br base @Server Booster
    ```
  </Step>

  <Step title="Configure Limits (Optional)">
    ```bash theme={null}
    ~br limit 1
    ~br share max 5
    ~br share limit 3
    ```
  </Step>

  <Step title="Test Creation">
    As a booster, test creating a role:

    ```bash theme={null}
    ~br create crimson My Role
    ```
  </Step>
</Steps>

***

## Usage Examples

<Tabs>
  <Tab title="Basic Creation">
    ```bash theme={null}
    # Create role with name only
    ~br create Awesome Member

    # Create with hex color
    ~br create #5865F2 Discord Blue

    # Create with color name
    ~br create gold Golden Role
    ```
  </Tab>

  <Tab title="Customization">
    ```bash theme={null}
    # Change color
    ~br color crimson

    # Rename role (wait 60s between renames)
    ~br name New Cool Name

    # Set icon (requires Level 2 boost)
    ~br icon 🔥

    # Use avatar color
    ~br dominant

    # Random color
    ~br random
    ```
  </Tab>

  <Tab title="Sharing">
    ```bash theme={null}
    # Share with user
    ~br share @username

    # See who has your role
    ~br share list

    # Leave a shared role
    ~br share remove @SomeRole
    ```
  </Tab>

  <Tab title="Admin Setup">
    ```bash theme={null}
    # Set base role
    ~br base @Booster

    # Configure limits
    ~br limit 1
    ~br share max 5
    ~br share limit 3

    # List all booster roles
    ~br list

    # Link existing role
    ~br link @user @ExistingRole
    ```
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Base role not set" icon="exclamation-triangle">
    **Problem:** "Base Role Not Set" error

    **Solution:**

    1. Create a role for the base position
    2. Position it where booster roles should appear
    3. Set it with `~br base @role`
    4. Ensure bot's role is above it
  </Accordion>

  <Accordion title="Already have a booster role" icon="copy">
    **Problem:** "You Already Have A Booster Role"

    **Solutions:**

    * Remove your current role: `~br remove`
    * Check configured limit: `~br limit`
    * Admins can increase limit if needed
  </Accordion>

  <Accordion title="Failed to create/edit role" icon="ban">
    **Problem:** "Failed To Create Booster Role" or "Failed To Change Color"

    **Solutions:**

    * Verify bot has Manage Roles permission
    * Check bot's role is above base role
    * Ensure bot's role is above all booster roles
    * Check role name is under 100 characters
  </Accordion>

  <Accordion title="Role icons not working" icon="image-slash">
    **Problem:** "This Server Doesn't Have Role Icons Unlocked"

    **Solution:**

    * Server must be boosted to Level 2 (7+ boosts)
    * Cannot be bypassed, it's a Discord limitation
    * Tell your members to boost the server!
  </Accordion>

  <Accordion title="Share request timing out" icon="clock">
    **Problem:** "Share Request Timed Out"

    **Solutions:**

    * Target user must click Accept/Decline within 30 seconds
    * Ask them to be ready before sending the request
    * Cooldown: wait 2 seconds between share attempts
  </Accordion>

  <Accordion title="Reached maximum shared roles" icon="users-slash">
    **Problem:** "Has Reached The Maximum Of X Shared Booster Roles"

    **Solutions:**

    * User must remove some shared roles: `~br share remove @role`
    * Admin can increase limit: `~br share limit <higher number>`
    * Remove unused shared roles to free up slots
  </Accordion>

  <Accordion title="Rename cooldown active" icon="timer">
    **Problem:** "Please Wait X Seconds Before Renaming Again"

    **Solution:**

    * 60-second cooldown between renames
    * Wait for cooldown to expire
    * This prevents spam and API abuse
  </Accordion>
</AccordionGroup>

***

## Boost Level Requirements

<CardGroup cols={3}>
  <Card title="Level 0" icon="0">
    **0-1 Boosts**

    * ✅ Create booster roles
    * ✅ Customize colors
    * ✅ Set names
    * ❌ Role icons
  </Card>

  <Card title="Level 1" icon="1">
    **2+ Boosts**

    * ✅ All Level 0 features
    * ✅ Animated server icon
    * ✅ Custom invite background
    * ❌ Role icons
  </Card>

  <Card title="Level 2+" icon="2">
    **7+ Boosts**

    * ✅ All Level 1 features
    * ✅ **Role icons unlocked**
    * ✅ Server banner
    * ✅ 1080p screen share
  </Card>
</CardGroup>

***

## Related Features

<CardGroup cols={2}>
  <Card title="Booster Messages" icon="message" href="/booster-messages">
    Send automatic thank you messages when members boost
  </Card>

  <Card title="Autorole" icon="user-tag" href="/autorole">
    Automatically assign roles to boosters when they boost
  </Card>
</CardGroup>