Enums

A GraphQL enum is a special scalar restricted to a fixed set of allowed values. Enums work as both input and output types. In C#, a standard enum maps directly to a GraphQL enum type.

GraphQL schema

enum UserRole {
  GUEST
  STANDARD
  ADMINISTRATOR
}

type Query {
  role: UserRole
  usersByRole(role: UserRole): [User]
}

Client query

{
  usersByRole(role: ADMINISTRATOR) {
    id
  }
}

When an enum appears in a JSON response or in a variables object, it is represented as a string ("ADMINISTRATOR"). When used directly in a query argument, it is a literal without quotes (ADMINISTRATOR).

Defining an Enum Type#

Hot Chocolate picks up any C# enum that appears in a resolver's return type or parameters and exposes it as a GraphQL enum.

Naming Conventions#

Hot Chocolate converts C# enum member names to UPPER_SNAKE_CASE following the GraphQL convention:

The enum type name defaults to the C# type name (UserRole).

Overriding Names#

Use [GraphQLName] to set an explicit name on the type or individual values.

Both approaches produce the following schema:

enum Role {
  VISITOR
  STANDARD
  ADMINISTRATOR
}

Ignoring Values#

You can exclude individual enum members from the GraphQL schema.

Binding to Non-Enum Types#

In code-first, you can bind an enum type to any .NET type, such as string.

public class UserRoleType : EnumType<string>
{
    protected override void Configure(IEnumTypeDescriptor<string> descriptor)
    {
        descriptor.Name("UserRole");

        descriptor
            .Value("Default")
            .Name("STANDARD");
    }
}

This is useful when enum values come from configuration or a database rather than a compile-time C# enum.

Next Steps#

• Need to define output types? See Object Types.
• Need nullable or required fields? See Non-Null.
• Need to document enum values? See Documentation.
• Need to deprecate an enum value? See Versioning.