Skip to content

Document role gradient colors #7549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jun 26, 2025
+77 −32
Merged

Document role gradient colors #7549

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
ce76562
feat: document role gradient colors
DA-344 May 9, 2025
84bc5af
object
DA-344 May 9, 2025
5dba1a6
comma
DA-344 May 9, 2025
36185b9
features and more clear docs
DA-344 May 9, 2025
b751c60
tables
DA-344 May 9, 2025
99b2a50
typo on permissions.md
DA-344 May 9, 2025
1c3d89d
add note about holographic style
DA-344 Jun 24, 2025
366b6ca
Merge branch 'role-gradient-colors' of https://github.com/da-344/disc…
DA-344 Jun 24, 2025
44fbc45
Reword info block on RoleColors
DA-344 Jun 25, 2025
d393bd6
's
DA-344 Jun 25, 2025
4697b9e
Update based on the review
DA-344 Jun 25, 2025
dc32e77
's
DA-344 Jun 25, 2025
ff1b4f3
apply suggestions and fix tables
DA-344 Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 28 additions & 18 deletions docs/resources/guild.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,7 @@ Fields specific to the `GUILD_CREATE` event are listed in the [Gateway Events do
| VERIFIED | guild is verified |
| VIP_REGIONS | guild has access to set 384kbps bitrate in voice (previously VIP voice servers) |
| WELCOME_SCREEN_ENABLED | guild has enabled the welcome screen |
| ENHANCED_ROLE_COLORS | guild is able to set gradient colors to roles |

###### Mutable Guild Features

Expand Down Expand Up @@ -824,6 +825,11 @@ Returns the [guild](/docs/resources/guild#guild-object) object for the given id.
"permissions": "49794752",
"position": 0,
"color": 0,
"colors": {
"primary_color": 0,
"secondary_color": null,
"tertiary_color": null
},
"hoist": false,
"managed": false,
"mentionable": false
Expand Down Expand Up @@ -1225,15 +1231,16 @@ This endpoint supports the `X-Audit-Log-Reason` header.

###### JSON Params

| Field | Type | Description | Default |
|---------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
| name | string | name of the role, max 100 characters | "new role" |
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
| color | integer | RGB color value | 0 |
| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
| mentionable | boolean | whether the role should be mentionable | false |
| Field | Type | Description | Default |
|---------------|-----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| name | string | name of the role, max 100 characters | "new role" |
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
| color | integer | RGB color value | 0 |
| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role colors | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
| mentionable | boolean | whether the role should be mentionable | false |

## Modify Guild Role Positions
<Route method="PATCH">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/roles</Route>
Expand Down Expand Up @@ -1268,15 +1275,18 @@ This endpoint supports the `X-Audit-Log-Reason` header.

###### JSON Params

| Field | Type | Description |
|---------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| name | string | name of the role, max 100 characters |
| permissions | string | bitwise value of the enabled/disabled permissions |
| color | integer | RGB color value |
| hoist | boolean | whether the role should be displayed separately in the sidebar |
| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
| mentionable | boolean | whether the role should be mentionable |
| Field | Type | Description |
|----------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| name | string | name of the role, max 100 characters |
| permissions | string | bitwise value of the enabled/disabled permissions |
| color* | integer | RGB color value |
| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
| hoist | boolean | whether the role should be displayed separately in the sidebar |
| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
| mentionable | boolean | whether the role should be mentionable |

\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.

## Modify Guild MFA Level
<Route method="POST">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/mfa</Route>
Expand Down
61 changes: 47 additions & 14 deletions docs/topics/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,23 +203,26 @@ Roles represent a set of permissions attached to a group of users. Roles have na

###### Role Structure

| Field | Type | Description |
|----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| id | snowflake | role id |
| name | string | role name |
| color | integer | integer representation of hexadecimal color code |
| hoist | boolean | if this role is pinned in the user listing |
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
| unicode_emoji? | ?string | role unicode emoji |
| position | integer | position of this role (roles with the same position are sorted by id) |
| permissions | string | permission bit set |
| managed | boolean | whether this role is managed by an integration |
| mentionable | boolean | whether this role is mentionable |
| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| Field | Type | Description |
|-----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| id | snowflake | role id |
| name | string | role name |
| color* | integer | integer representation of hexadecimal color code |
| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
| hoist | boolean | if this role is pinned in the user listing |
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
| unicode_emoji? | ?string | role unicode emoji |
| position | integer | position of this role (roles with the same position are sorted by id) |
| permissions | string | permission bit set |
| managed | boolean | whether this role is managed by an integration |
| mentionable | boolean | whether this role is mentionable |
| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |

Roles without colors (`color == 0`) do not count towards the final computed color in the user list.

\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.

###### Role Tags Structure

Tags with type `null` represent booleans. They will be present and set to `null` if they are "true", and will be not present if they are "false".
Expand All @@ -233,13 +236,43 @@ Tags with type `null` represent booleans. They will be present and set to `null`
| available_for_purchase? | null | whether this role is available for purchase |
| guild_connections? | null | whether this role is a guild's linked role |

###### Role Colors Object

This object will always be filled with `primary_color` being the role's `color`. Other fields can only be set to a non-null value if the guild has the `ENHANCED_ROLE_COLORS` [guild feature](/docs/resources/guild#guild-object-guild-features).

| Field | Type | Description |
|------------------|----------|--------------------------------------------------------------------------------------------------------|
| primary_color | integer | the primary color for the role |
| secondary_color | ?integer | the secondary color for the role, this will make the role a gradient between the other provided colors |
| tertiary_color | ?integer | the tertiary color for the role, this will turn the gradient into a holographic style |

:::info
When sending `tertiary_color` the API enforces the role color to be a holographic style with values of:
`primary_color = 11127295`, `secondary_color = 16759788`, and `tertiary_color = 16761760`.
:::

###### Default Role Colors Object

```json
"colors": {
"primary_color": 0,
"secondary_color": null,
"tertiary_color": null
}
```

###### Example Role

```json
{
"id": "41771983423143936",
"name": "WE DEM BOYZZ!!!!!!",
"color": 3447003,
"colors": {
"primary_color": 3447003,
"secondary_color": null,
"tertiary_color": null
},
"hoist": true,
"icon": "cf3ced8600b777c9486c6d8d84fb4327",
"unicode_emoji": null,
Expand Down