discord.js | Role

Search...

Role

export class Role extends Base

export class Role extends Base

Represents a role on Discord.

Extends

Base

Readonly

client:Client<true>

The client that instantiated this

Inherited from Base

color:number

The base 10 color of the role

Readonly

createdAt:Date

The time the role was created at

Readonly

createdTimestamp:number

The timestamp the role was created at

Readonly

editable:boolean

Whether the role is editable by the client user

flags:RoleFlagsBitField

The flags of this role

guild:Guild

The guild that the role belongs to

Readonly

hexColor:HexColorString

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

hoist:boolean

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

icon:string | null

The icon hash of the role

id:Snowflake

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

managed:boolean

Whether or not the role is managed by an external service

Readonly

members:Collection<Snowflake, GuildMember>

The cached guild members that have this role

mentionable:boolean

Whether or not the role can be mentioned by anyone

name:string

The name of the role

permissions:Readonly<PermissionsBitField>

The permissions of the role

Readonly

position:number

The position of the role in the role manager

rawPosition:number

The raw position of the role from the API

tags:RoleTagData | null

The tags this role has

unicodeEmoji:string | null

The unicode emoji for the role

comparePositionTo(role):number

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

Returns

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

Example

// 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}`);

// 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}`);

Name	Type	Optional	Description
role	RoleResolvable	No	Role to compare to this one

delete(reason?):Promise<Role>

Deletes the role.

Example

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

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

Name	Type	Optional	Description
reason	string	Yes	Reason for deleting this role

edit(options):Promise<Role>

Edits the role.

Example

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

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

Name	Type	Optional	Description
options	RoleEditOptions	No	The options to provide

equals(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.

Name	Type	Optional	Description
role	Role	No	Role to compare with

iconURL(options?):string | null

A link to the role's icon

Returns

Name	Type	Optional	Description
options	ImageURLOptions	Yes	Options for the image URL

permissionsIn(channel, checkAdmin?):Readonly<PermissionsBitField>

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

Name	Type	Optional	Description
channel	NonThreadGuildBasedChannel \| Snowflake	No	The guild channel to use as context
checkAdmin	boolean	Yes	Whether having the PermissionFlagsBits.Administrator permission will return all permissions

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

Sets a new color for the role.

Example

// Set the color of a role
role.setColor('#FF0000')
  .then(updated => console.log(`Set color of role to ${updated.color}`))
  .catch(console.error);

// Set the color of a role
role.setColor('#FF0000')
  .then(updated => console.log(`Set color of role to ${updated.color}`))
  .catch(console.error);

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

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

Sets whether or not the role should be hoisted.

Example

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

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

Name	Type	Optional	Description
hoist	boolean	Yes	Whether or not to hoist the role
reason	string	Yes	Reason for setting whether or not the role should be hoisted

setIcon(icon, reason?):Promise<Role>

Sets a new icon for the role.

Name	Type	Optional	Description
icon	BufferResolvable \| Base64Resolvable \| EmojiResolvable \| null	No	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	Yes	Reason for changing the role's icon

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

Sets whether this role is mentionable.

Example

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

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

Name	Type	Optional	Description
mentionable	boolean	Yes	Whether this role should be mentionable
reason	string	Yes	Reason for setting whether or not this role should be mentionable

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

Sets a new name for the role.

Example

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

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

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

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

Sets the permissions of the role.

Example

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

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

Example

// Remove all permissions from a role
role.setPermissions(0n)
  .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);

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

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

Sets the new position of the role.

Example

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

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

Name	Type	Optional	Description
position	number	No	The new position for the role
options	SetRolePositionOptions	Yes	Options for setting the position

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

Sets a new unicode emoji for the role.

Example

// 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);

// 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);

Name	Type	Optional	Description
unicodeEmoji	string \| null	No	The new unicode emoji for the role
reason	string	Yes	Reason for changing the role's unicode emoji

toJSON():unknown

toString():RoleMention

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

Example

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

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

valueOf():string