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

# Role

> Read the permissions, position and members of a role, and change or delete it

A `Role` is a role of a server. You get one from `guild.roles`, `member.roles`, `member.highestRole`, a `role` option of a [command](https://www.chapterjs.org/commands/options.md) or `guild.createRole()`. Every server has an @everyone role that every member has: `guild.everyoneRole`, whose id is the id of the server.

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import type { Guild } from 'chapterjs';

async function createModerators(guild: Guild) {
  const role = await guild.createRole({
    name: 'Moderators',
    permissions: ['KickMembers', 'BanMembers', 'ModerateMembers'],
    hoist: true,
  });
  return `${role} was created.`; // "<@&id> was created."
}
```

> [!NOTE]
>
> How to check and give permissions is in [Permissions](https://www.chapterjs.org/reference/permissions.md); how a command receives a role is in [Options](https://www.chapterjs.org/commands/options.md).

## Properties

**id** `Snowflake`

The unique id Discord gave it.

**createdAt** `Date`

When it was created: a Discord id contains its creation date.

**guildId** `Snowflake`

The id of the server of the role.

**guild** `Guild`

The server of the role.

**name** `string`

The name of the role.

**color** `number`

The color as a number (`0xff0000`); `0` means no color.

**hoist** `boolean`

Whether members with this role are shown apart in the member list.

**position** `number`

Where the role is in the hierarchy: the higher, the more powerful.

**permissions** `Permissions`

What the role allows in the server. See [Permissions](https://www.chapterjs.org/reference/permissions.md).

**managed** `boolean`

Whether the role belongs to an integration (a bot, boosters...).

**mentionable** `boolean`

Whether everyone can mention the role.

**unicodeEmoji** `string | null`

The standard emoji shown next to the role, when it has one.

**isEveryone** `boolean`

Whether this is the @everyone role, which every member has.

**members** `GuildMember[]`

The members that have this role, among the ones the bot knows.

> [!NOTE]
>
> `members` is read from the members the bot remembers (see [Memory](https://www.chapterjs.org/memory.md)), so it is not always every member with the role.

## Helpers

These read what the bot remembers: they never send a request.

### iconURL()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
iconURL(options?: ImageOptions): string | null
```

The URL of the icon of the role, when it has one. See [ImageOptions](https://www.chapterjs.org/reference/helpers.md#imageoptions).

### isHigherThan()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
isHigherThan(other: Role): boolean
```

Whether this role is above another one in the hierarchy. With the same position, the oldest role is above.

[Discord documentation](https://docs.discord.com/developers/topics/permissions#permission-hierarchy)

### toString()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
toString(): string
```

`<@&id>`: mentions the role when put in a message.

### toJSON()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
toJSON(): object
```

The data of Discord as a plain object, with camelCase names.

## Actions

### edit()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
edit(options: RoleEditOptions, reason?: string): Promise<Role>
```

Changes the role. See [RoleEditOptions](https://www.chapterjs.org/reference/options.md#roleeditoptions).

[Discord documentation](https://docs.discord.com/developers/resources/guild#modify-guild-role)

### delete()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
delete(reason?: string): Promise<void>
```

Deletes the role.

[Discord documentation](https://docs.discord.com/developers/resources/guild#delete-guild-role)

## Types

`RoleEditOptions` is in [Options](https://www.chapterjs.org/reference/options.md#roleeditoptions), next to `RoleCreateOptions`. `Permissions` is in [Permissions](https://www.chapterjs.org/reference/permissions.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.