syntx.js

cmd.role.create

Creates a new role in the guild. Supports solid, gradient, and holographic color styles, as well as icons, permissions, and position.

JavaScript
const { cmd } = require("syntx.js");

await cmd.role.create({ name, color, colors, colorStyle, hoist, mentionable, permissions, icon, unicodeEmoji, position, reason }, message);

Parameters

ParameterTypeRequiredDescription
namestringYesThe name of the role.
colorstring | numberNoShorthand for setting the primary color. Ignored if colors.primary is also set.
colorsobjectNoFine-grained color control. See color styles below.
colorStylestringNoColor rendering style: "solid", "gradient", or "holographic". Defaults to "solid".
hoistbooleanNoWhether to display members with this role separately in the member list. Defaults to false.
mentionablebooleanNoWhether anyone can mention this role. Defaults to false.
permissionsstring[]NoArray of permission flag strings to grant. Defaults to [].
iconstringNoURL or file path for the role icon. Requires the guild to have at least Level 2 boost.
unicodeEmojistringNoUnicode emoji to use as the role icon. Requires at least Level 2 boost.
positionnumberNoPosition of the role in the hierarchy.
reasonstringNoAudit log reason for the action.
messagediscord.js MessageYesA guild message or interaction, used to access the guild.

Color styles

"solid" (default)

A single flat color. Use color or colors.primary to set it:

JavaScript
{ color: "#ff5733" }
// or
{ colors: { primary: "#ff5733" }, colorStyle: "solid" }

Passing colors.secondary alongside "solid" throws a SyntxError.

"gradient"

A two-color gradient. Both colors.primary and colors.secondary are required:

JavaScript
{
  colorStyle: "gradient",
  colors: { primary: "#ff5733", secondary: "#3399ff" }
}

"holographic"

Discord's built-in holographic rainbow effect. No custom colors can be provided; the palette is applied automatically by Discord:

JavaScript
{ colorStyle: "holographic" }

Passing any color or colors value alongside "holographic" throws a SyntxError.

Returns

An object describing the created role, with the same shape as the return value of cmd.role.info, except without the assignedMembers field.

FieldTypeDescription
idstringThe new role's ID.
namestringThe role's name.
colorstringThe primary color as a hex string.
colorStylestringThe resolved color style: "solid", "gradient", or "holographic".
colorsobjectThe full color set: { primary, secondary, tertiary }.
iconstring | nullURL of the role icon, or null.
unicodeEmojistring | nullThe role's unicode emoji, or null.
positionnumberThe role's position in the hierarchy.
permissionsstring[]Array of granted permission flag strings.
hoistbooleanWhether the role is hoisted.
mentionablebooleanWhether the role is mentionable.
managedbooleanWhether the role is managed by an integration.
editablebooleanWhether the bot can edit this role.
flagsstring[]Array of role flag strings.
tagsobject | nullRole tags, if any.
createdAtDateWhen the role was created.

Examples

Create a basic role

JavaScript
client.command({
  name: "createrole",
  content: async (message) => {
    const role = await cmd.role.create(
      {
        name: "Members",
        color: "#3399ff",
        hoist: true,
        mentionable: true,
      },
      message
    );

    message.reply(`Role created: <@&${role.id}>`);
  },
});

Create a gradient role

JavaScript
client.command({
  name: "gradientrole",
  content: async (message) => {
    const role = await cmd.role.create(
      {
        name: "Nitro Fan",
        colorStyle: "gradient",
        colors: {
          primary: "#ff73fa",
          secondary: "#7289da",
        },
        hoist: true,
      },
      message
    );

    message.reply(`Gradient role created: <@&${role.id}>`);
  },
});

Create a holographic role

JavaScript
client.command({
  name: "hologrole",
  content: async (message) => {
    const role = await cmd.role.create(
      {
        name: "✨ Special",
        colorStyle: "holographic",
        mentionable: false,
        reason: "Special event role",
      },
      message
    );

    message.reply(`Holographic role created: <@&${role.id}>`);
  },
});

Warning

The bot must have the Manage Roles permission and its own highest role must be above the position where the new role will be placed. Role icons and unicode emojis require the guild to have at least Level 2 boost. If any of these conditions are not met, a SyntxError is thrown.