EDA.Role.Colors (EDA v0.4.0)

A role's colours: solid, gradient, or holographic.

Supersedes the role's single color field, which Discord deprecated — JDA marks its equivalent getColor() as @ReplaceWith("getColors().getPrimary()"), and discord.js sends only colors when editing a role, never color.

Four styles

style/1 returns :default, :solid, :gradient or :holographic, mirroring JDA's isDefault() / isSolid() / isGradient() / isHolographic(). Two distinctions matter:

:default — no colour at all. Discord represents this as primary_color: 0, which is not the same as an explicitly chosen black. Measured across 201 roles on 8 real guilds, 78 were in this state — 39%, and only 8 of those were @everyone. Treating them as solid would mis-colour most of a typical guild's roles;
:solid — a real single colour;
:gradient — secondary_color is set, tertiary_color is not;
:holographic — tertiary_color is set, and Discord then forces all three values to 11127295, 16759788, 16761760. You cannot pick your own holographic colours. Use holographic/0 rather than writing them out.

Reading

role.colors
#=> %EDA.Role.Colors{primary_color: 10382335, secondary_color: 12427263, tertiary_color: nil}

EDA.Role.Colors.style(role.colors)  #=> :gradient

Writing

EDA.Role.set_colors(guild_id, role_id, EDA.Role.Colors.gradient(0xFF0000, 0x00FF00))
EDA.Role.set_colors(guild_id, role_id, EDA.Role.Colors.holographic())
EDA.Role.set_colors(guild_id, role_id, EDA.Role.Colors.solid(0x5865F2))

Writing needs an eligible guild

Setting a gradient or holographic colour on an ineligible guild fails with HTTP 403, code 670006 "Missing guild feature" (EDA.Error.missing_guild_feature/0). The relevant feature is not advertised: ENHANCED_ROLE_COLORS appeared in no guild's features array, including one with seven gradient roles already in place. So there is no reliable pre-check — attempt the write and handle the error. Reading is unaffected.

Observed behaviour

Probed against a real guild (2026-09-19): every role carried all three keys, primary_color equalled the legacy color on all 57 roles, and 7 used a gradient. The ENHANCED_ROLE_COLORS guild feature was absent despite gradients being in use, so do not gate reads on that feature.

Summary

Types

style()

The colour style of a role.

t()

Functions

default?(colors)

Returns true when the role has no colour of its own.

from_raw(raw)

Parses the raw colors object. Returns nil when absent.

gradient(primary, secondary)

A two-colour gradient.

gradient?(colors)

Returns true for a two-colour gradient — not for holographic roles.

holographic()

The holographic style, with the three values Discord enforces.

holographic?(colors)

Returns true for the holographic style.

holographic_primary()

The primary_color Discord enforces for holographic roles.

holographic_secondary()

The secondary_color Discord enforces for holographic roles.

holographic_tertiary()

The tertiary_color Discord enforces for holographic roles.

solid(primary)

A solid, single-colour role.

solid?(colors)

Returns true for a role with one real colour — not for an uncoloured role.

style(arg1)

Returns the colour style: :default, :solid, :gradient or :holographic.

to_map(colors)

Converts to the snake_case object Discord expects in a role payload.

Types

style()

@type style() :: :default | :solid | :gradient | :holographic

The colour style of a role.

t()

@type t() :: %EDA.Role.Colors{
  primary_color: integer() | nil,
  secondary_color: integer() | nil,
  tertiary_color: integer() | nil
}

Functions

default?(colors)

@spec default?(t() | nil) :: boolean()

Returns true when the role has no colour of its own.

Examples

iex> EDA.Role.Colors.default?(%EDA.Role.Colors{primary_color: 0})
true

iex> EDA.Role.Colors.default?(%EDA.Role.Colors{primary_color: 1})
false

iex> EDA.Role.Colors.default?(nil)
true

from_raw(raw)

@spec from_raw(map() | nil) :: t() | nil

Parses the raw colors object. Returns nil when absent.

gradient(primary, secondary)

@spec gradient(integer(), integer()) :: t()

A two-colour gradient.

Examples

iex> EDA.Role.Colors.gradient(0xFF0000, 0x00FF00)
%EDA.Role.Colors{primary_color: 16711680, secondary_color: 65280, tertiary_color: nil}

gradient?(colors)

@spec gradient?(t() | nil) :: boolean()

Returns true for a two-colour gradient — not for holographic roles.

Examples

iex> EDA.Role.Colors.gradient?(%EDA.Role.Colors{primary_color: 1, secondary_color: 2})
true

iex> EDA.Role.Colors.gradient?(EDA.Role.Colors.holographic())
false

iex> EDA.Role.Colors.gradient?(nil)
false

holographic()

@spec holographic() :: t()

The holographic style, with the three values Discord enforces.

Discord ignores any other values once tertiary_color is sent, so this takes no arguments on purpose.

Examples

iex> EDA.Role.Colors.holographic()
%EDA.Role.Colors{primary_color: 11127295, secondary_color: 16759788, tertiary_color: 16761760}

holographic?(colors)

@spec holographic?(t() | nil) :: boolean()

Returns true for the holographic style.

Examples

iex> EDA.Role.Colors.holographic?(EDA.Role.Colors.holographic())
true

iex> EDA.Role.Colors.holographic?(%EDA.Role.Colors{primary_color: 1, secondary_color: 2})
false

holographic_primary()

@spec holographic_primary() :: integer()

The primary_color Discord enforces for holographic roles.

holographic_secondary()

@spec holographic_secondary() :: integer()

The secondary_color Discord enforces for holographic roles.

holographic_tertiary()

@spec holographic_tertiary() :: integer()

The tertiary_color Discord enforces for holographic roles.

solid(primary)

@spec solid(integer()) :: t()

A solid, single-colour role.

Examples

iex> EDA.Role.Colors.solid(0x5865F2)
%EDA.Role.Colors{primary_color: 5793266, secondary_color: nil, tertiary_color: nil}

solid?(colors)

@spec solid?(t() | nil) :: boolean()

Returns true for a role with one real colour — not for an uncoloured role.

Examples

iex> EDA.Role.Colors.solid?(%EDA.Role.Colors{primary_color: 1})
true

iex> EDA.Role.Colors.solid?(%EDA.Role.Colors{primary_color: 0})
false

iex> EDA.Role.Colors.solid?(EDA.Role.Colors.holographic())
false

style(arg1)

@spec style(t() | nil) :: style()

Returns the colour style: :default, :solid, :gradient or :holographic.

primary_color: 0 means no colour, not black — it is :default, as in JDA.

Examples

iex> EDA.Role.Colors.style(%EDA.Role.Colors{primary_color: 1})
:solid

iex> EDA.Role.Colors.style(%EDA.Role.Colors{primary_color: 0})
:default

iex> EDA.Role.Colors.style(%EDA.Role.Colors{primary_color: 1, secondary_color: 2})
:gradient

iex> EDA.Role.Colors.style(EDA.Role.Colors.holographic())
:holographic

iex> EDA.Role.Colors.style(nil)
:default

to_map(colors)

@spec to_map(t()) :: map()

Converts to the snake_case object Discord expects in a role payload.

Keys whose value is nil are omitted rather than sent as null, so a solid colour does not clear a gradient by accident.

Examples

iex> EDA.Role.Colors.to_map(EDA.Role.Colors.solid(255))
%{primary_color: 255}

iex> EDA.Role.Colors.to_map(EDA.Role.Colors.gradient(1, 2))
%{primary_color: 1, secondary_color: 2}