---
alias: "fc.provider.graphql"
aliases:
  - fc.provider.graphql
category: content
module: Core
---
# fc.provider.graphql

Execute an additional GraphQL query and provide results as data context for descendants.

## When to Use
- Load related entity data not in the page query
- Fetch locations, inventory, or reference data
- Secondary queries that don't fit in the primary page query

## Key Props
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `query` | string (GraphQL) | **Yes** | GraphQL query string |
| `path` | string | **Yes** | Path to the data root in the query response. If the path points to a connection, auto-paginates. E.g., `"locationById"`, `"orders"` |
| `variables` | Record<string, any> | No | Query variables -- supports template strings |
| `max` | number | No | Max records to fetch when auto-paginating (default: 1000, **hardcoded cap: 1000** -- values above 1000 are clamped) |
| `loadingBehavior` | string | No | `"wait"`, `"wait-with-animation"`, `"pass-immediately"` (default) |
| `toastMessages` | object | No | Override toast messages: `{ maxResultsReached?: string }` -- custom warning when max record limit is hit |

## Data Binding
Query results become the data context for descendants. Variables can reference parent data: `{ "id": "{{fulfilment.location.id}}" }`.

**Implicit template variables** available in `variables` templates: `{{activeContext.id}}`, `{{activeLocation.id}}`, `{{activeRetailer.id}}`, `{{activeUser.username}}`, `{{params.id}}` (route params), plus all parent data fields.

## Descendants
Yes — receive the provider's query results as their data context.

## Composition Patterns
- `fc.provider.graphql` > `fc.card.attribute` (show location details)
- `fc.provider.graphql` > `fc.list` (show related entities)

## Gotchas
- **Do NOT nest inside `fc.list`** -- both compete for pagination, causes conflicts
- Query is a string, not gql tagged template
- Variables are rendered as templates before query execution
- `loadingBehavior: "wait"` blocks rendering until ALL pages are fetched
- **Implicit `dataProviderState`** is passed to all descendants as part of the data context. Values: `"loading"`, `"ok"`, `"error"`, `"max"`. Use in conditionals: `"{{dataProviderState}}"` matches `"ok"` to show content only after data loads
- `max` is clamped to 1000 even if you specify a higher value (`Math.min(max, 1000)`)
- When the max record limit is reached, a toast warning is shown automatically (customizable via `toastMessages.maxResultsReached`)

## Validation Rules
P09 (CRITICAL — query required), D01 (valid GraphQL), D06 (query must be defined)

## Manifest Example
```json
{
  "component": "fc.provider.graphql",
  "props": {
    "query": "query location($id: ID!) { locationById(id: $id) { id ref name } }",
    "path": "locationById",
    "variables": { "id": "{{fulfilment.fromLocation.id}}" },
    "loadingBehavior": "wait"
  },
  "descendants": [
    { "component": "fc.card.attribute", "props": { "title": "Location", "attributes": [{ "label": "Name", "value": "{{locationById.name}}" }] } }
  ]
}
```

## AI Parse Notes
- **Primary intent:** Declarative Mystique component definition for manifests.
- **Selection signals:** Match by `alias`, category, and required `Key Props`.
- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
- **Safety checks:** Validate required props and data bindings before manifest generation.
