class Role

extends

Base
export class Role extends Base

Represents a role on Discord.

readonly
client : Client

The client that instantiated this

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: RoleResolvable
) : number

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

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

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

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

Deletes the role.

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

edit(
options: RoleEditOptions
) : Promise<Role>

Edits the role.

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

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.

iconURL(
options?: ImageURLOptions
) : string | null

A link to the role's icon

permissionsIn(
channel: NonThreadGuildBasedChannel | Snowflake
checkAdmin?: boolean
) : Readonly<PermissionsBitField>

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

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

Sets a new color for the role.

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

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

Sets whether or not the role should be hoisted.

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

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

Sets a new icon for the role.

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

Sets whether this role is mentionable.

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

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

Sets a new name for the role.

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

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

Sets the permissions of the role.

Examples:
// 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);
// Remove all permissions from a role
role.setPermissions(0n)
  .then(updated => console.log(`Updated permissions to ${updated.permissions.bitfield}`))
  .catch(console.error);

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

Sets the new position of the role.

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

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

Sets a new unicode emoji for the role.

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

toJSON() : unknown

toString() : RoleMention

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

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

valueOf() : string

Inherited from: Base