Input type for complex arguments in GraphQL

Introduction

Input types let you send structured data to GraphQL queries or mutations. They help organize complex information clearly.

When you want to send multiple related values together in a query or mutation.

When you need to pass nested or grouped data like an address or user profile.

When you want to keep your API clean and easy to understand by grouping inputs.

When you want to reuse the same input structure in different queries or mutations.

Syntax

GraphQL

input InputName {
  field1: Type1
  field2: Type2
  ...
}

# Then use it in a query or mutation
mutation SomeMutation($input: InputName!) {
  someAction(input: $input) {
    resultField
  }
}

Input types are defined with the input keyword, not type.

Input types can only contain fields with input types (scalars, enums, or other input types).

Examples

This defines an input type for an address with required street and city, and optional zip code.

GraphQL

input AddressInput {
  street: String!
  city: String!
  zip: String
}

This mutation takes a complex user input to add a new user.

GraphQL

mutation AddUser($user: UserInput!) {
  addUser(user: $user) {
    id
    name
  }
}

Input type with nested input type for address.

GraphQL

input UserInput {
  name: String!
  age: Int
  address: AddressInput
}

Sample Program

This example shows how to define input types for a user and their address, then use them in a mutation to create a user with detailed info.

GraphQL

input AddressInput {
  street: String!
  city: String!
  zip: String
}

input UserInput {
  name: String!
  age: Int
  address: AddressInput
}

mutation CreateUser($user: UserInput!) {
  createUser(user: $user) {
    id
    name
    age
    address {
      street
      city
      zip
    }
  }
}

Important Notes

Input types cannot have fields that are other object types; only input types or scalars.

Use ! to mark fields as required.

Input types help keep your API organized and easier to maintain.

Summary

Input types group related input fields for queries and mutations.

They allow nested and reusable input structures.

Defined with input keyword and used as argument types.