# Lists - Hot Chocolate

> Expose .NET collections as GraphQL list types in Hot Chocolate, covering supported collection types, list nullability, and nested list definitions.

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

C#

```
[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](https://chillicream.com/docs/hotchocolate/defining-a-schema/non-null) 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:

C#

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

C#

```
[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](https://chillicream.com/docs/hotchocolate/defining-a-schema/non-null).
- **Need pagination instead of full lists?** See [Pagination](https://chillicream.com/docs/hotchocolate/fetching-data/pagination).
- **Need to filter or sort lists?** See [Filtering](https://chillicream.com/docs/hotchocolate/fetching-data/filtering) and [Sorting](https://chillicream.com/docs/hotchocolate/fetching-data/sorting).
[Edit this page on GitHub](https://github.com/ChilliCream/graphql-platform/edit/main/website/content/docs/hotchocolate/defining-a-schema/lists.md)

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