ProductHot Chocolate

Lists

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

GraphQL

type Query {
  users: [User!]!
}

Client query

GraphQL

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

C# return type	GraphQL type (NRT enabled)
`List<User>`	`[User!]!`
`User[]`	`[User!]!`
`IEnumerable<User>`	`[User!]!`
`IReadOnlyList<User>`	`[User!]!`
`IQueryable<User>`	`[User!]!`
`List<User?>`	`[User]!`
`List<User>?`	`[User!]`

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

Defining List Fields#

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.

C# type	GraphQL type	Meaning
`List<string>`	`[String!]!`	Non-null list of non-null items
`List<string?>`	`[String]!`	Non-null list, items can be null
`List<string>?`	`[String!]`	List itself can be null, items are non-null
`List<string?>?`	`[String]`	Both list and items can be null

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.

[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.

Edit this page on GitHub

On this page