GraphQL lists represent ordered collections of elements. When a resolver returns any .NET collection type, Hot Chocolate exposes it as a list in the schema.

GraphQL schema

type Query {
  users: [User!]!
}

Client query

{
  users {
    id
    name
  }
}

The response contains an ordered array of objects matching the requested fields.

Supported Collection Types

Hot Chocolate recognizes common .NET collection types and maps them to GraphQL lists.

Any type implementing IEnumerable<T> is treated as a list.

Defining List Fields

// Types/UserQueries.cs
[QueryType]
public static partial class UserQueries
{
    public static List<User> GetUsers(CatalogContext db)
        => db.Users.ToList();
}

The return type List<User> is automatically mapped to [User!]! when NRT is enabled.

List Nullability

Lists have two layers of nullability: the list itself and its items. With nullable reference types enabled, Hot Chocolate infers both layers from your C# types.

If you need to override the inferred nullability, use [GraphQLType] or the descriptor API:

// Override to allow null items
[GraphQLType(typeof(ListType<StringType>))]
public List<string> Tags { get; set; }

Nested Lists

Hot Chocolate supports nested lists (lists of lists). This pattern is useful for representing matrix-like data.

// Types/GridQueries.cs
[QueryType]
public static partial class GridQueries
{
    public static List<List<int>> GetMatrix()
        => [[1, 2], [3, 4]];
}

This produces matrix: [[Int!]!]! in the schema.

Next Steps

• Need to control nullability? See Non-Null.
• Need pagination instead of full lists? See Pagination.
• Need to filter or sort lists? See Filtering and Sorting.