GraphiQL API Documentation
    Preparing search index...

    Module @graphiql/react

    Changelog | API Docs | NPM

    @graphiql/react

    A React SDK for building integrated GraphQL developer experiences for the web.

    This package contains a set of building blocks that allow its users to build GraphQL IDEs with ease. It's the set of components that make up GraphiQL, the first and official GraphQL IDE, owned and maintained by the GraphQL Foundation.

    There are two kinds of building blocks that this package provides: Stateful context providers for state management and simple UI components.

    All the state for your GraphQL IDE lives in multiple contexts. The easiest way to get started is by using the GraphiQLProvider component that renders all the individual providers.

    GraphiQLProvider needs either a transport or a fetcher prop (the two are mutually exclusive) to know how to run GraphQL requests against a given endpoint. A transport is an object with a send(request) method; you can easily create one using the createTransport function from the @graphiql/toolkit package. fetcher is the older, deprecated-but-still-supported alternative: a plain function that returns an execution result directly, with no access to the underlying HTTP response.

    import { GraphiQLProvider } from '@graphiql/react';
    import { createTransport } from '@graphiql/toolkit';
    
    const transport = createTransport({
      url: 'https://my.graphql.api/graphql',
    });
    
    function MyGraphQLIDE() {
      return (
        
          
    Hello GraphQL
    ); }

    Inside the provider you can now use any UI component provided by @graphiql/react. For example, you can render an operation editor like this:

    import { QueryEditor } from '@graphiql/react';
    
    function MyGraphQLIDE() {
      return (
        
          
    ); }

    The package also ships the necessary CSS that all its UI components need. You can import them from @graphiql/react/style.css.

    Note: In order for these styles to apply, the UI components need to be rendered inside an element that has a class name graphiql-container.

    By default, the UI components will try to use the Roboto font for regular text and the Fira Code font for mono-space text. If you want to use the default fonts you can load them using these files:

    • @graphiql/react/font/roboto.css
    • @graphiql/react/font/fira-code.css.

    You can, of course, use any other method to load these fonts (for example, loading them from Google Fonts).

    Further details on how to use @graphiql/react can be found in the reference implementation of a GraphQL IDE - GraphiQL - in the graphiql package.

    GraphiQL uses a set of state management stores, each responsible for a specific part of the IDE's behavior. These stores contain all logic related to state management and can be accessed via custom React hooks.

    • useMonaco: Access monaco-editor exports and the monaco-graphql instance. Designed for safe use in SSR environments.
    • useGraphiQL: Access the current state.
    • useGraphiQLActions: Trigger actions that mutate the state. This hook never rerenders.

    The useGraphiQLActions hook exposes all actions across store slices. The useGraphiQL hook provides access to the following store slices:

    Store Slice Responsibilities
    storage Provides a storage API that can be used to persist state in the browser (by default using localStorage)
    editor Manages query, variables, headers, and response editors and tabs
    execution Handles the execution of GraphQL requests
    plugin Manages plugins and the currently active plugin
    schema Fetches, validates, and stores the GraphQL schema
    theme Manages the current theme and provides a method to update it
    import { useGraphiQL, useGraphiQLActions } from '@graphiql/react';

    // Get an action to fetch the schema and an action to change theme
    const { introspect, setTheme } = useGraphiQLActions();

    // Use a selector to access specific parts of the state like current schema and theme
    const { schema, theme } = useGraphiQL(state => ({
    schema: state.schema,
    theme: state.theme,
    }));

    All store properties are documented using TSDoc comments. If you're using an IDE like VSCode for development, these descriptions will show up in auto-complete tooltips. All these descriptions can also be found in the API Docs.

    All the components from @graphiql/react have been designed with customization in mind. We achieve this using CSS variables.

    As of v6 the customization surface is the OKLCH design-token set in the tokens.css file.

    GraphiQL's UI colors come from the v6 OKLCH design tokens documented below. The v5 --color-* HSL variables are deprecated and kept only for backward compatibility — see Deprecated: v5 HSL variables.

    Colors are defined as OKLCH component triplets — L% C H (lightness, chroma, hue) — stored without the oklch() wrapper so callers can add alpha at the use site:

    background: oklch(var(--bg-canvas));
    color: oklch(var(--fg-default) / 0.6);

    The tokens are scoped to [data-theme='dark'] and [data-theme='light'] rather than a media query, so a given variable resolves correctly regardless of which theme is active. The full set, defined in tokens.css, with when to reach for each:

    Backgrounds — surfaces, ordered by how they stack:

    • --bg-canvas — the primary content surface: editors, side panels, the active tab. The base layer everything else sits on.
    • --bg-elevated — bars and floating chrome above the canvas: the tab strip, panel and response headers, tooltips, dropdown menus, popovers.
    • --bg-subtle — recessed fills inside a surface: text inputs, secondary-button faces, segmented-control tracks, inline code.
    • --bg-overlay — transient interaction layers painted on top of a surface: hover, selected, and pressed states.

    Borders — increasing prominence:

    • --border-default — the standard divider and component outline; your default choice.
    • --border-muted — a fainter separator for low-emphasis internal divisions (menu-item rules, quiet section breaks).
    • --border-strong — the most visible edge, for inputs and dividers that must read clearly against busy content.

    Foreground — text and icon emphasis, brightest to faintest:

    • --fg-strong — high-emphasis text: headings, active or selected labels.
    • --fg-default — body text; the default content color.
    • --fg-muted — secondary text and resting icons: labels, captions, metadata.
    • --fg-subtle — tertiary text and quieter icons, one step below muted.
    • --fg-disabled — text and icons of disabled controls.
    • --fg-dim — the faintest marks: decorative or comment-level.

    Accents — the raw hue palette for syntax and status. You rarely set these directly; components and the --type-* tokens assign the roles (links and focus rings → --accent-blue, errors → --accent-red, success → --accent-green, deprecation → --accent-orange, and so on). The full set: --accent-blue, --accent-green, --accent-green-light, --accent-yellow, --accent-orange, --accent-red, --accent-purple, --accent-pink.

    Type-name categories — --type-composite, --type-scalar, --type-enum, --type-input. Color GraphQL type names by kind; see the note below.

    Run button — --btn-primary and --btn-primary-border: fill and border for the primary action (Run). A fixed mid-tone green tuned to keep light text legible in both themes — reserve it for the main call-to-action rather than general buttons.

    Radii — --radius-sm (4px; small controls: buttons, inputs, chips), --radius-md (6px; menus and cards), --radius-lg (8px; dialogs and large panels).

    Shadow — --shadow-popover: the elevation shadow for floating surfaces (menus, tooltips, dialogs).

    Type-name categories. In the schema-aware plugins (doc explorer, query builder), type names are colored by GraphQL kind rather than a single color: object/interface/union share --type-composite, scalars use --type-scalar, enums use --type-enum, and input objects use --type-input. By default each aliases an --accent-* token, so you can retint either the accent or the --type-* token directly. (In the light theme --type-input isn't an alias — --accent-yellow is only AA-contrast-safe as a background fill, not as text, so it gets its own darker gold.)

    If you're building a plugin that renders type names and want it to match, @graphiql/react exports a typeCategory(type) helper that maps any GraphQLType to 'scalar' | 'enum' | 'input' | 'composite' (unwrapping list and non-null wrappers first). Apply the corresponding --type-* token to your markup; the internal attribute and class names GraphiQL uses for this are not part of the public API.

    Deprecated (v6): The v5 --color-* HSL variables (--color-primary, --color-neutral, --color-base, and so on) described below are deprecated as of v6 and are no longer read by any component. They remain defined — frozen at their v5 values — for backward compatibility, but overriding them no longer re-themes GraphiQL. Retheme with the OKLCH tokens above instead; the v6 migration guide maps each v5 variable to its v6 replacement.

    The deprecated v5 colors are defined using the HSL format: all CSS variables for colors are defined as a list of the three values that make up HSL (hue, saturation and lightness).

    This approach allowed @graphiql/react to use transparent colors by passing the value of the CSS variable in the hsla function. The v6 OKLCH tokens keep the same idea — the triplet is composed with oklch(var(--x) / <alpha>) — so transparency still works at the call site.

    If you want to develop with @graphiql/react locally - in particular when working on the graphiql package - all you need to do is run pnpm dev in the package folder in a separate terminal. This will build the package using Vite. When using it in combination with pnpm dev:graphiql (running in the repo root) this will give you auto-reloading when working on graphiql and @graphiql/react simultaneously.

    KeyCode
    KeyMod
    Range
    Uri
    ActivityRailProps
    GraphiQLPlugin
    SchemaReference
    SettingsDialogProps
    SlicesWithActions
    CleanupFn
    ConnectionStatus
    Density
    EditorProps
    FontSize
    GraphiQLPluginContext
    GraphiQLSettings
    GraphQLTypeCategory
    KeycapHintProps
    MethodPillProps
    ModifierKey
    MonacoEditor
    OnBeforeSendCallback
    OnResponseCallback
    Operation
    PanelHeaderProps
    PluginTransportContext
    ResponseView
    SaveHandler
    SegmentedControlOption
    SegmentedControlProps
    SettingsTheme
    TabsState
    Theme
    TopBarProps
    VarHeadersStripProps
    VarHeadersTab
    ActivityRail
    ArgumentIcon
    Button
    ButtonGroup
    ChevronDownIcon
    ChevronLeftIcon
    ChevronUpIcon
    CloseIcon
    CopyIcon
    createBoundedUseStore
    DeprecatedArgumentIcon
    DeprecatedEnumValueIcon
    DeprecatedFieldIcon
    Dialog
    DirectiveIcon
    DocsFilledIcon
    DocsIcon
    EnumValueIcon
    ExecuteButton
    FieldIcon
    GraphiQLProvider
    GraphQLLogoIcon
    HeaderEditor
    HistoryIcon
    ImagePreview
    ImplementsIcon
    isMacOs
    KEY_MAP
    KeyboardShortcutIcon
    KeycapHint
    MagnifyingGlassIcon
    markdown
    MarkdownContent
    MergeIcon
    MethodPill
    MODIFIER
    onEditorContainerKeyDown
    PanelHeader
    PenIcon
    PlayIcon
    PlusIcon
    PortalProvider
    PrettifyIcon
    QueryBuilderIcon
    QueryEditor
    ReloadIcon
    ResponseEditor
    RootTypeIcon
    SaveIcon
    SETTINGS_STORAGE_KEY
    SettingsDialog
    SettingsIcon
    SidePanel
    Spinner
    StarFilledIcon
    StarIcon
    StatusBar
    StopIcon
    Tab
    Tabs
    ToolbarButton
    ToolbarMenu
    Tooltip
    TopBar
    TrashIcon
    TypeIcon
    UnStyledButton
    useDidUpdate
    useMonaco
    VarHeadersStrip
    VariableEditor
    VisuallyHidden
    cleanupDisposables
    createEditor
    debounce
    formatJSONC
    formatShortcutForOS
    getOrCreateModel
    parseJSONC
    pick
    SegmentedControl
    tryParseJSONC
    typeCategory
    useChangeHandler
    useDragResize
    useEditorState
    useGraphiQL
    useGraphiQLActions
    useGraphiQLPluginContext
    useGraphiQLSettings
    useHeadersEditorState
    useOperationsEditorState
    useOptimisticState
    usePortalContainer
    useVariablesEditorState