# Enums - Hot Chocolate

> Define GraphQL enum types in Hot Chocolate: C# enums map automatically, and `EnumType` descriptors let you rename values and control value binding.

Canonical source: https://chillicream.com/docs/hotchocolate/defining-a-schema/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**

GraphQL

```
enum UserRole {
  GUEST
  STANDARD
  ADMINISTRATOR
}

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

**Client query**

GraphQL

```
{
  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.

C#

```
public enum UserRole
{
    Guest,
    Standard,
    Administrator
}

[QueryType]
public static partial class UserQueries
{
    public static User[] GetUsersByRole(UserRole role)
    {
        // ...
    }
}
```

No extra registration is needed. The source generator discovers `UserRole` through the resolver parameter.

## Naming Conventions

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

| C# member        | GraphQL value        |
| ---------------- | -------------------- |
| Guest            | GUEST                |
| HeadOfDepartment | HEAD\_OF\_DEPARTMENT |

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.

C#

```
[GraphQLName("Role")]
public enum UserRole
{
    [GraphQLName("VISITOR")]
    Guest,
    Standard,
    Administrator
}
```

Both approaches produce the following schema:

GraphQL

```
enum Role {
  VISITOR
  STANDARD
  ADMINISTRATOR
}
```

## Ignoring Values

You can exclude individual enum members from the GraphQL schema.

C#

```
public enum UserRole
{
    [GraphQLIgnore]
    Internal,
    Guest,
    Standard,
    Administrator
}
```

## Binding to Non-Enum Types

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

C#

```
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](https://chillicream.com/docs/hotchocolate/defining-a-schema/object-types).
- **Need nullable or required fields?** See [Non-Null](https://chillicream.com/docs/hotchocolate/defining-a-schema/non-null).
- **Need to document enum values?** See [Documentation](https://chillicream.com/docs/hotchocolate/defining-a-schema/documentation).
- **Need to deprecate an enum value?** See [Versioning](https://chillicream.com/docs/hotchocolate/defining-a-schema/versioning).
[Edit this page on GitHub](https://github.com/ChilliCream/graphql-platform/edit/main/website/content/docs/hotchocolate/defining-a-schema/enums.md)

Last updated on **June 30, 2026** by **Tobias Tengler**