Role

classe · Source

Represents a role on Discord.

Extends: Base

Properties

guild

guild: Guild

The guild that the role belongs to Source

icon

nullable

icon: string

The icon hash of the role Source

unicodeEmoji

nullable

unicodeEmoji: string

The unicode emoji for the role Source

id

id: Snowflake

The role's id (unique to the guild it is part of) Source

name

name: string

The name of the role Source

color

deprecated

color: number

The base 10 color of the role Source

colors

colors: RoleColors

The colors of the role Source

hoist

hoist: boolean

If true, users that are part of this role will appear in a separate category in the users list Source

rawPosition

rawPosition: number

The raw position of the role from the API Source

permissions

permissions: Readonly<Permissions>

The permissions of the role Source

managed

managed: boolean

Whether or not the role is managed by an external service Source

mentionable

mentionable: boolean

Whether or not the role can be mentioned by anyone Source

tags

nullable

tags: Object

The tags this role has Source

flags

flags: Readonly<RoleFlags>

The flags of this role Source

createdTimestamp

readonly

createdTimestamp: number

The timestamp the role was created at Source

createdAt

readonly

createdAt: Date

The time the role was created at Source

deleted

deprecated

deleted: boolean

Whether or not the role has been deleted Source

hexColor

readonly

hexColor: string

The hexadecimal version of the role color, with a leading hashtag Source

members

readonly

members: Collection<Snowflake, GuildMember>

The cached guild members that have this role Source

editable

readonly

editable: boolean

Whether the role is editable by the client user Source

position

readonly

position: number

The position of the role in the role manager Source

client

readonly

client: Client

The client that instantiated this Source

Methods

comparePositionTo

comparePositionTo(role: RoleResolvable): number

Compares this role's position to another role's. Parameters

Name	Type	Description
role	RoleResolvable	Role to compare to this one

Returns: number — Negative number if this role's position is lower (other role's is higher), positive number if this one is higher (other's is lower), 0 if equal

// Compare the position of a role to another
const roleCompare = role.comparePositionTo(otherRole);
if (roleCompare >= 1) console.log(`${role.name} is higher than ${otherRole.name}`);

Source

edit

edit(data: RoleData, reason?: string): Promise<Role>

Edits the role. Parameters

Name	Type	Description
data	RoleData	The new data for the role
reason?	string	Reason for editing this role

Returns: Promise<Role>

// Edit a role
role.edit({ name: 'new role' })
  .then(updated => console.log(`Edited role name to ${updated.name}`))
  .catch(console.error);

Source

permissionsIn

permissionsIn(channel: GuildChannel | Snowflake, checkAdmin?: boolean): Readonly<Permissions>

Returns channel.permissionsFor(role). Returns permissions for a role in a guild channel, taking into account permission overwrites. Parameters

Name	Type	Description
channel	GuildChannel | Snowflake	The guild channel to use as context
checkAdmin?	boolean	Whether having ADMINISTRATOR will return all permissions Default: true.

Returns: Readonly<Permissions>Source

setName

setName(name: string, reason?: string): Promise<Role>

Sets a new name for the role. Parameters

Name	Type	Description
name	string	The new name of the role
reason?	string	Reason for changing the role's name

Returns: Promise<Role>

// Set the name of the role
role.setName('new role')
  .then(updated => console.log(`Updated role name to ${updated.name}`))
  .catch(console.error);

Source

setColor

deprecated

setColor(color: ColorResolvable, reason?: string): Promise<Role>

Sets a new color for the role. Parameters

Name	Type	Description
color	ColorResolvable	The color of the role
reason?	string	Reason for changing the role's color

Returns: Promise<Role>Source

setColors

setColors(colors: RoleColorsResolvable, reason?: string): Promise<Role>

Sets new colors for the role. Parameters

Name	Type	Description
colors	RoleColorsResolvable	The colors of the role
reason?	string	Reason for changing the role's colors

Returns: Promise<Role>

// Set the colors of a role
role.setColors({ primaryColor: '#FF0000', secondaryColor: '#00FF00', tertiaryColor: '#0000FF' })
  .then(updated => console.log(`Set colors of role to ${updated.colors}`))
  .catch(console.error);

// Set holographic colors using constants
role.setColors({
  primaryColor: Constants.HolographicStyle.Primary,
  secondaryColor: Constants.HolographicStyle.Secondary,
  tertiaryColor: Constants.HolographicStyle.Tertiary,
})
  .then(updated => console.log(`Set holographic colors for role ${updated.name}`))
  .catch(console.error);

Source

setHoist

setHoist(hoist?: boolean, reason?: string): Promise<Role>

Sets whether or not the role should be hoisted. Parameters

Name	Type	Description
hoist?	boolean	Whether or not to hoist the role Default: true.
reason?	string	Reason for setting whether or not the role should be hoisted

Returns: Promise<Role>

// Set the hoist of the role
role.setHoist(true)
  .then(updated => console.log(`Role hoisted: ${updated.hoist}`))
  .catch(console.error);

Source

setPermissions

setPermissions(permissions: PermissionResolvable, reason?: string): Promise<Role>

Sets the permissions of the role. Parameters

Name	Type	Description
permissions	PermissionResolvable	The permissions of the role
reason?	string	Reason for changing the role's permissions

Returns: Promise<Role>

// Set the permissions of the role
role.setPermissions([Permissions.FLAGS.KICK_MEMBERS, Permissions.FLAGS.BAN_MEMBERS])
  .then(updated => console.log(`Updated permissions to ${updated.permissions.bitfield}`))
  .catch(console.error);

// Remove all permissions from a role
role.setPermissions(0n)
  .then(updated => console.log(`Updated permissions to ${updated.permissions.bitfield}`))
  .catch(console.error);

Source

setMentionable

setMentionable(mentionable?: boolean, reason?: string): Promise<Role>

Sets whether this role is mentionable. Parameters

Name	Type	Description
mentionable?	boolean	Whether this role should be mentionable Default: true.
reason?	string	Reason for setting whether or not this role should be mentionable

Returns: Promise<Role>

// Make the role mentionable
role.setMentionable(true)
  .then(updated => console.log(`Role updated ${updated.name}`))
  .catch(console.error);

Source

setIcon

setIcon(icon: BufferResolvable | Base64Resolvable | EmojiResolvable, reason?: string): Promise<Role>

Sets a new icon for the role. Parameters

Name	Type	Description
icon	BufferResolvable | Base64Resolvable | EmojiResolvable	The icon for the role The EmojiResolvable should belong to the same guild as the role. If not, pass the emoji's URL directly
reason?	string	Reason for changing the role's icon

Returns: Promise<Role>Source

setUnicodeEmoji

setUnicodeEmoji(unicodeEmoji: string, reason?: string): Promise<Role>

Sets a new unicode emoji for the role. Parameters

Name	Type	Description
unicodeEmoji	string	The new unicode emoji for the role
reason?	string	Reason for changing the role's unicode emoji

Returns: Promise<Role>

// Set a new unicode emoji for the role
role.setUnicodeEmoji('🤖')
  .then(updated => console.log(`Set unicode emoji for the role to ${updated.unicodeEmoji}`))
  .catch(console.error);

Source

setPosition

setPosition(position: number, options?: SetRolePositionOptions): Promise<Role>

Sets the new position of the role. Parameters

Name	Type	Description
position	number	The new position for the role
options?	SetRolePositionOptions	Options for setting the position

Returns: Promise<Role>

// Set the position of the role
role.setPosition(1)
  .then(updated => console.log(`Role position: ${updated.position}`))
  .catch(console.error);

Source

delete

async

async delete(reason?: string): Promise<Role>

Deletes the role. Parameters

Name	Type	Description
reason?	string	Reason for deleting this role

Returns: Promise<Role>

// Delete a role
role.delete('The role needed to go')
  .then(deleted => console.log(`Deleted role ${deleted.name}`))
  .catch(console.error);

Source

fetchMemberIds

fetchMemberIds(): Promise<Array<Snowflake>>

Fetches the member ids for this role in the guild. This only returns 100 member ids Returns: Promise<Array<Snowflake>>Source

iconURL

iconURL(options?: StaticImageURLOptions): string

A link to the role's icon Parameters

Name	Type	Description
options?	StaticImageURLOptions	Options for the image URL Default: {}.

Returns: stringSource

equals

equals(role: Role): boolean

Whether this role equals another role. It compares all properties, so for most operations it is advisable to just compare role.id === role2.id as it is much faster and is often what most users need. Parameters

Name	Type	Description
role	Role	Role to compare with

Returns: booleanSource

toString

toString(): string

When concatenated with a string, this automatically returns the role's mention instead of the Role object. Returns: string

// Logs: Role: <@&123456789012345678>
console.log(`Role: ${role}`);

Source

comparePositions

static · deprecated

comparePositions(role1: Role, role2: Role): number

Compares the positions of two roles. Parameters

Name	Type	Description
role1	Role	First role to compare
role2	Role	Second role to compare

Returns: number — Negative number if the first role's position is lower (second role's is higher), positive number if the first's is higher (second's is lower), 0 if equal Source