# Fumadocs (Framework Mode, Next.js): Headless
URL: /docs/next/integrations/graphql/headless
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/integrations/graphql/headless.mdx

The state and logic of GraphQL pages, without UI.

## Overview [#overview]

Everything outside `@fumadocs/graphql/ui` is headless.

| Path                           | Module                                                               |
| ------------------------------ | -------------------------------------------------------------------- |
| `@fumadocs/graphql`            | the page: the schema built from SDL, cross-links and your components |
| `@fumadocs/graphql/operation`  | an operation: its field, title, directives and examples              |
| `@fumadocs/graphql/type-docs`  | a named type: its kind, directives, relations and usages             |
| `@fumadocs/graphql/playground` | the state of playground, sending operations and subscriptions        |

## Page [#page]

`createGraphQLRenderer()` takes your components and returns `<GraphQLPage />`, which accepts the props of generated pages.

```tsx title="components/api-page.tsx"
'use client';
import { type CodeBlockProps, createGraphQLRenderer } from '@fumadocs/graphql';
import { Operation } from '@/components/my-operation';
import { TypeDocs } from '@/components/my-type';

export const GraphQLPage = createGraphQLRenderer({
  components: {
    Operation,
    TypeDocs,
    // `root` is a field-like root, or a schema coordinate like `Query.orders()`
    SchemaUI: ({ client, root }) => (
      <pre>{`${client.name}: ${typeof root === 'string' ? root : root.type}`}</pre>
    ),
    CodeBlock({ lang, code }: CodeBlockProps) {
      return (
        <pre>
          <code className={`language-${lang}`}>{code}</code>
        </pre>
      );
    },
  },
});
```

| Component   | Renders                                                 |
| ----------- | ------------------------------------------------------- |
| `Operation` | each operation of the page, see [Operation](#operation) |
| `TypeDocs`  | each named type of the page, see [Type](#type)          |
| `SchemaUI`  | a type, argument or field in detail                     |
| `Layout`    | optional, wraps the rendered items                      |

Pass `typeLinks` and `operationLinks` to override the [cross-links](/docs/next/integrations/graphql/api-page#cross-linking) of pre-generated pages.

### Hooks [#hooks]

Components under the page read its state.

| Hook                           | Returns                                                            |
| ------------------------------ | ------------------------------------------------------------------ |
| `useGraphQL()`                 | the built `schema`, its `sdl`, the page links and examples         |
| `useComponents()`              | the components passed to the page                                  |
| `useTypeLink(name)`            | the page URL of a named type, `undefined` when unlinked            |
| `useOperationLink(kind, name)` | the page URL of an operation                                       |
| `useRenderContext()`           | the render options of the page, like `playground` and `codeUsages` |

To render operations yourself, mount `<GraphQLProvider sdl={sdl} components={...} />` in place of `createGraphQLRenderer()`.

## Operation [#operation]

`<OperationProvider />` derives the details of an operation.

```tsx title="components/my-operation.tsx"
'use client';
import { useComponents } from '@fumadocs/graphql';
import {
  OperationProvider,
  type PageOperationProps,
  useOperation,
} from '@fumadocs/graphql/operation';

export function Operation({ kind, name }: PageOperationProps) {
  return (
    <OperationProvider kind={kind} name={name}>
      <Content />
    </OperationProvider>
  );
}

function Content() {
  const { title, field, examples, selected, select } = useOperation();
  const { CodeBlock, SchemaUI } = useComponents();
  const example = examples.at(selected);

  return (
    <>
      <h2>{title}</h2>
      {field.args.map((arg) => (
        <SchemaUI
          key={arg.name}
          client={{ name: arg.name, rootId: arg.name }}
          root={{ type: arg.type }}
        />
      ))}
      {examples.map((item, i) => (
        <button key={i} onClick={() => select(i)}>
          {item.name ?? 'Example'}
        </button>
      ))}
      {example && <CodeBlock lang="graphql" code={example.query} />}
    </>
  );
}
```

`examples` are the ones from the [`examples` option](/docs/next/integrations/graphql/server#examples), or a generated one. `selected` is shared by everything under the provider, like the example card and the playground.

### OperationInfo

| Prop         | Type                                  | Description                                                                                                           |
| ------------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `kind`       | `GraphQL.OperationKind`               |                                                                                                                       |
| `name`       | `string`                              |                                                                                                                       |
| `title`      | `string`                              | display title of the operation, e.g. `createOrder` -> `Create Order`.                                                 |
| `field`      | `GraphQLField<unknown, unknown, any>` |                                                                                                                       |
| `directives` | `DirectiveNode[]`                     | custom directive applications                                                                                         |
| `examples`   | `GraphQL.OperationExample[]`          | examples from the `examples` option of server, otherwise a generated one, empty when the operation cannot be sampled. |
| `selected`   | `number`                              | index of the selected example, shared by the example cards and playground                                             |
| `select`     | `(index: number) => void`             |                                                                                                                       |

### OperationExample

| Prop           | Type                                   | Description                                             |
| -------------- | -------------------------------------- | ------------------------------------------------------- |
| `name?`        | `string \| undefined`                  | the title of example, `undefined` for the generated one |
| `description?` | `string \| undefined`                  | Markdown                                                |
| `query`        | `string`                               |                                                         |
| `variables?`   | `Record<string, unknown> \| undefined` |                                                         |
| `response`     | `unknown`                              |                                                         |

## Type [#type]

`<TypeProvider />` derives the details of a named type.

```tsx title="components/my-type.tsx"
'use client';
import { useComponents } from '@fumadocs/graphql';
import { type PageTypeProps, TypeProvider, useNamedType } from '@fumadocs/graphql/type-docs';

export function TypeDocs({ name }: PageTypeProps) {
  return (
    <TypeProvider name={name}>
      <Content />
    </TypeProvider>
  );
}

function Content() {
  const { name, kind, type, relations } = useNamedType();
  const { SchemaUI } = useComponents();

  return (
    <>
      <h2>
        {name} ({kind})
      </h2>
      {relations.usages.returnedBy.map((op) => (
        <span key={`${op.kind}:${op.name}`}>{op.name}</span>
      ))}
      <SchemaUI client={{ name, rootId: name, as: 'body' }} root={{ type }} />
    </>
  );
}
```

### NamedTypeInfo

| Prop         | Type                                                                                                                                                                                                           | Description                   |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `name`       | `string`                                                                                                                                                                                                       |                               |
| `kind`       | `GraphQL.NamedTypeKind`                                                                                                                                                                                        |                               |
| `type`       | `GraphQLNamedType`                                                                                                                                                                                             |                               |
| `directives` | `DirectiveNode[]`                                                                                                                                                                                              | custom directive applications |
| `relations`  | `{ implements: readonly GraphQLInterfaceType[]; unions: readonly GraphQLUnionType[]; implementedBy: readonly GraphQLObjectType[]; possibleTypes: readonly GraphQLObjectType[]; usages: TypeDocs.TypeUsages; }` |                               |

`relations` connects the type to the rest of schema:

| Relation        | Is                                          |
| --------------- | ------------------------------------------- |
| `implements`    | the interfaces it implements                |
| `unions`        | the unions including it, for objects        |
| `implementedBy` | the objects implementing it, for interfaces |
| `possibleTypes` | the members of unions                       |
| `usages`        | where it appears across the schema          |

### TypeUsages

| Prop         | Type                      | Description                                                                                  |
| ------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
| `returnedBy` | `TypeDocs.OperationRef[]` | operations whose return type resolves to this named type (list/non-null wrappers unwrapped). |
| `memberOf`   | `TypeDocs.FieldRef[]`     | object/interface/input object fields typed as this named type.                               |
| `inputFor`   | `TypeDocs.OperationRef[]` | operations with a direct argument of this named type.                                        |
| `argumentOf` | `TypeDocs.FieldRef[]`     | field arguments (on non-root types) typed as this named type.                                |

## Playground [#playground]

`usePlayground()` holds the playground of the operation under `<OperationProvider />`, configured by the page's [`playground` option](/docs/next/integrations/graphql/api-page#playground).

```tsx title="components/my-playground.tsx"
'use client';
import { StfProvider, useFieldValue } from '@fumari/stf';
import { useOperation } from '@fumadocs/graphql/operation';
import { usePlayground } from '@fumadocs/graphql/playground';

export function MyPlayground() {
  const { field } = useOperation();
  const { stf, open, url, changeUrl, query, setQuery, send, isSending, response } = usePlayground();

  return (
    // opening restores the endpoint and headers of previous visits
    <details onToggle={(e) => e.currentTarget.open && open()}>
      <summary>Try it</summary>
      <input value={url} onChange={(e) => changeUrl(e.target.value)} />
      <textarea value={query} onChange={(e) => setQuery(e.target.value)} />
      <StfProvider value={stf}>
        {field.args.map((arg) => (
          <Variable key={arg.name} name={arg.name} />
        ))}
      </StfProvider>
      <button disabled={isSending} onClick={send}>
        Send
      </button>
      {response?.result.type === 'response' && <pre>{response.result.body}</pre>}
    </details>
  );
}

function Variable({ name }: { name: string }) {
  const [value, setValue] = useFieldValue(['variables', name]);

  return (
    <input
      aria-label={name}
      value={String(value ?? '')}
      onChange={(e) => setValue(e.target.value)}
    />
  );
}
```

Subscriptions use `subscribe()`, `stop()`, `status` and `log` in place of `send()` and `response`.

### Playground

| Prop            | Type                                               | Description                                                                                                       |
| --------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `stf`           | `Stf`                                              | the form: `variables` and `headers` of the request                                                                |
| `url`           | `string`                                           | the endpoint, empty until `open()` restores it                                                                    |
| `changeUrl`     | `(url: string) => void`                            | headers are kept by endpoint origin, a new origin swaps them out                                                  |
| `query`         | `string`                                           |                                                                                                                   |
| `setQuery`      | `(query: string) => void`                          |                                                                                                                   |
| `loaded`        | `number`                                           | index of the example in the editor and form                                                                       |
| `example?`      | `GraphQL.OperationExample \| undefined`            |                                                                                                                   |
| `select`        | `(index: number) => void`                          | select an example on the page, and load it                                                                        |
| `reset`         | `() => void`                                       | load the selected example again                                                                                   |
| `open`          | `() => void`                                       | when the dialog opens: restore the endpoint and headers of previous visits, load the example selected on the page |
| `send`          | `() => Promise<void>`                              | send a query or mutation, its result becomes `response`                                                           |
| `isSending`     | `boolean`                                          |                                                                                                                   |
| `response?`     | `PlaygroundModule.PlaygroundResponse \| undefined` |                                                                                                                   |
| `clearResponse` | `() => void`                                       |                                                                                                                   |
| `subscribe`     | `() => void`                                       | start a subscription, its events are added to `log`                                                               |
| `stop`          | `() => void`                                       |                                                                                                                   |
| `status`        | `PlaygroundModule.ConnectionStatus`                |                                                                                                                   |
| `log`           | `PlaygroundModule.LogEntry[]`                      |                                                                                                                   |
| `clearLog`      | `() => void`                                       |                                                                                                                   |

| Export                                | Does                                                                                      |
| ------------------------------------- | ----------------------------------------------------------------------------------------- |
| `useRequestValues()`                  | the `variables` and `headers` the form under `<StfProvider />` sends, following its edits |
| `executeGraphQL(request)`             | sends a query or mutation over HTTP POST, the default `fetcher`                           |
| `subscribeGraphQL(request, handlers)` | starts a subscription, returns a function to stop it                                      |
| `inputTypeToJsonSchema(type)`         | the JSON Schema of an input type, for forms of variables                                  |

`subscribeGraphQL()` picks the protocol by the URL scheme, like [`subscriptionUrl`](/docs/next/integrations/graphql/api-page#subscriptions).

```ts
import { subscribeGraphQL } from '@fumadocs/graphql/playground';

const stop = subscribeGraphQL(
  {
    url: 'wss://api.example.com/graphql',
    query: 'subscription { orderUpdated(id: "1") { status } }',
    headers: {},
  },
  {
    onNext: (result) => console.log(result),
    onError: (error) => console.error(error.type),
    onComplete: () => console.log('completed'),
  },
);

// no handler is called after it
stop();
```

### SubscriptionHandlers

| Prop         | Type                                                  | Description                                                                                                               |
| ------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `onOpen?`    | `(() => void) \| undefined`                           | the subscription started                                                                                                  |
| `onNext`     | `(result: unknown) => void`                           | an execution result of the subscription, like `{ data }` or `{ errors }`, including the errors of a rejected subscription |
| `onError`    | `(error: PlaygroundModule.SubscriptionError) => void` | the connection failed, it ends the subscription                                                                           |
| `onComplete` | `() => void`                                          | the server completed the subscription, it ends the subscription                                                           |