Feature-dependent fields
Request optional fields only when a client feature or display mode needs them.
GraphQL · Directive
@include
@include conditionally includes a field or fragment when its required if argument evaluates to true. Use it to let runtime variables control whether optional selections are requested.
How it works
@include conditionally selects a field, fragment spread, or inline fragment during query execution. Its required Boolean argument controls inclusion: the selection is included when the argument evaluates to true and omitted otherwise.
Syntax
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENTParameters
| Name | Type | Description |
|---|---|---|
if | Boolean! | Controls whether the annotated selection is included; it must evaluate to true for inclusion. |
Returns
No standalone value; it controls whether the annotated field or fragment selection contributes to the query result.
Key points
- A field annotated with @include appears in the response only when its if argument evaluates to true.
- Clients attach @include to fields or fragment inclusions in an executable operation.
- @include is one of GraphQL's two built-in executable directives; the other is @skip.
- Spec-compliant GraphQL servers provide these built-in directives without requiring custom schema definitions.
Common mistakes
- When both directives are present, inclusion requires @include to be true and @skip to be false; either opposing condition omits the selection.
- @include is a built-in directive that compliant GraphQL servers must support, alongside @skip.
Example: Conditionally include a fragment
query GetUser($showDetails: Boolean!) {
user {
id
name
...UserDetails @include(if: $showDetails)
}
}
fragment UserDetails on User {
email
createdAt
}The fragment is included in the response only when showDetails is true.
When to use it
Conditional fragment spreads
Enable or omit a reusable group of selections with one runtime Boolean.
Conditional type selections
Choose whether type-specific selections are requested in an inline fragment.
Interview questions
QWhat does @include do?
@include conditionally includes a field or fragment based on its if argument. The selection is executed only when that argument evaluates to true.
Follow-up: Where can it be applied? It is valid on fields, fragment spreads, and inline fragments.
QWhat is the signature of @include?
The directive takes a required Boolean argument: @include(if: Boolean!). A variable is commonly used so the client can choose the selection at runtime.
Follow-up: Why is the exclamation mark significant? It makes the argument non-null, so the operation must provide a Boolean value rather than null.
QHow does @include interact with @skip?
With both directives, the selection is included only when @skip is false and @include is true. Neither directive overrides the other.
Follow-up: What happens if @skip is true? The selection is omitted even when @include is true.
Related
@skipfieldsfragment spreadsinline fragmentsdirectivesvariables