Options
All
  • Public
  • Public/Protected
  • All
Menu

Package graphiql

GraphiQL

Security Notice: All versions of graphiql < 1.4.3 are vulnerable to an XSS attack in cases where the GraphQL server to which the GraphiQL web app connects is not trusted. Learn more in our security advisory.

NPM jsDelivr hits (npm) npm downloads Snyk Vulnerabilities for npm package npm bundle size (version) npm bundle size (version) License

/ˈɡrafək(ə)l/ A graphical interactive in-browser GraphQL IDE. Try the live demo.

Features

  • Full language support of the latest GraphQL Specification:
  • Syntax highlighting
  • Intelligent type ahead of fields, arguments, types, and more
  • Real-time error highlighting and reporting for queries and variables
  • Automatic query and variables completion
  • Automatic leaf node insertion for non-scalar fields
  • Documentation explorer with search and markdown support
  • Persisted state using localStorage
  • Simple API for adding custom plugins

Live Demos

Examples

Getting started

If you're looking to upgrade from graphiql@1.x to graphiql@2, check out the migration guide!

UMD

With unpkg/jsdelivr, etc.:

<link href="https://unpkg.com/graphiql/graphiql.min.css" rel="stylesheet" />
<script crossorigin src="https://unpkg.com/graphiql/graphiql.min.js"></script>

(see: Usage UMD Bundle below for more required script tags)

Usage

Using as package

The graphiql package can be installed using your favorite package manager. You also need to have react,react-dom and graphql installed which are peer dependencies of graphiql.

npm install --save graphiql react react-dom graphql

The package exports a bunch of React components:

  • The GraphiQLProvider components renders multiple context providers that encapsulate all state management
  • The GraphiQLInterface component renders the UI that makes up GraphiQL
  • The GraphiQL component is a combination of both the above components

There is a single prop that is required for the GraphiQL component called fetcher. A fetcher is a function that performs a request to a GraphQL API. It may return a Promise for queries or mutations, but also an Observable or an AsyncIterable in order to handle subscriptions or multipart responses.

An easy way to get create such a function is the createGraphiQLFetcher method exported from the @graphiql/toolkit package. If you want to implement your own fetcher function you can use the Fetcher type from @graphiql/toolkit to make sure the signature matches what GraphiQL expects.

The following is everything you need to render GraphiQL in your React application:

import { createGraphiQLFetcher } from '@graphiql/toolkit';
import { GraphiQL } from 'graphiql';
import React from 'react';
import ReactDOM from 'react-dom';

import 'graphiql/graphiql.css';

const fetcher = createGraphiQLFetcher({ url: 'https://my.backend/graphql' });

ReactDOM.render(
  <GraphiQL fetcher={fetcher} />,
  document.getElementById('root'),
);

Using as UMD bundle over CDN (Unpkg, JSDelivr, etc)

There exist pre-bundled static assets that allow you to easily render GraphiQL just by putting together a single HTML file. Check out the index.html file in the example project in this repository.

Customize

GraphiQL supports customization in UI and behavior by accepting React props and children.

Props

For props documentation, see the API Docs

Children

Parts of the UI can be customized by passing children to the GraphiQL or the GraphiQLInterface component.

  • <GraphiQL.Logo>: Replace the GraphiQL logo with your own.

  • <GraphiQL.Toolbar>: Add a custom toolbar below the execution button. Pass the empty <GraphiQL.Toolbar /> if an empty toolbar is desired. Use the components provided by @graphiql/react to create toolbar buttons with proper styles.

  • <GraphiQL.Footer>: Add a custom footer shown below the response editor.

Plugins

Starting with graphiql@2 there exists a simple plugin API that allow you to build your own custom tools right into GraphiQL.

There are two built-in plugins that come with GraphiQL: The documentation explorer and the query history. Both can be toggled using icons in the sidebar on the left side of the screen. When opened, they appear next to the sidebar in a resizable portion of the screen.

To define your own plugin, all you need is a JavaScript object with three properties:

  • title: A unique title for the plugin (this will show up in a tooltip when hovering over the sidebar icon)
  • icon: A React component that renders an icon which will be included in the sidebar
  • content: A React component that renders the plugin contents which will be shown next to the sidebar when opening the plugin

You can pass a list of plugin objects to the GraphiQL component using the plugins prop. You can also control the visibility state of plugins using the visiblePlugin prop and react to changes of the plugin visibility state using the onTogglePluginVisibility prop.

Inside the component you pass to content you can interact with the GraphiQL state using the hooks provided by @graphiql/react. As an example, check out how you can integrate the OneGraph Explorer in GraphiQL using the plugin API in the plugin package in this repo.

Theming

The GraphiQL interface uses CSS variables for theming, in particular for colors. Check out the root.css file for the available variables.

Overriding these variables is the only officially supported way of customizing the appearance of GraphiQL. Starting from version 2, class names are no longer be considered stable and might change between minor or patch version updates.

Editor Theme

The colors inside the editor can also be altered using CodeMirror editor themes. You can use the editorTheme prop to pass in the name of the theme. The CSS for the theme has to be loaded for the theme prop to work.

// In your document head:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.23.0/theme/solarized.css" />

// When rendering GraphiQL:
<GraphiQL editorTheme="solarized light" />

You can also create your own theme in CSS. As a reference, the default graphiql theme definition can be found here.

Index

References

Namespaces

Type aliases

Variables

Functions

Object literals

References

Argument

Re-exports Argument

ArgumentIcon

Re-exports ArgumentIcon

Button

Re-exports Button

ButtonGroup

Re-exports ButtonGroup

ChevronDownIcon

Re-exports ChevronDownIcon

ChevronLeftIcon

Re-exports ChevronLeftIcon

ChevronUpIcon

Re-exports ChevronUpIcon

CloseIcon

Re-exports CloseIcon

CommonEditorProps

Re-exports CommonEditorProps

CopyIcon

Re-exports CopyIcon

DOC_EXPLORER_PLUGIN

Re-exports DOC_EXPLORER_PLUGIN

DefaultValue

Re-exports DefaultValue

DeprecatedArgumentIcon

Re-exports DeprecatedArgumentIcon

DeprecatedEnumValueIcon

Re-exports DeprecatedEnumValueIcon

DeprecatedFieldIcon

Re-exports DeprecatedFieldIcon

DeprecationReason

Re-exports DeprecationReason

Dialog

Re-exports Dialog

Directive

Re-exports Directive

DirectiveIcon

Re-exports DirectiveIcon

DocExplorer

Re-exports DocExplorer

DocsFilledIcon

Re-exports DocsFilledIcon

DocsIcon

Re-exports DocsIcon

EditorContext

Re-exports EditorContext

EditorContextProvider

Re-exports EditorContextProvider

EditorContextProviderProps

Re-exports EditorContextProviderProps

EditorContextType

Re-exports EditorContextType

EnumValueIcon

Re-exports EnumValueIcon

ExecuteButton

Re-exports ExecuteButton

ExecutionContext

Re-exports ExecutionContext

ExecutionContextProvider

Re-exports ExecutionContextProvider

ExecutionContextProviderProps

Re-exports ExecutionContextProviderProps

ExecutionContextType

Re-exports ExecutionContextType

ExplorerContext

Re-exports ExplorerContext

ExplorerContextProvider

Re-exports ExplorerContextProvider

ExplorerContextProviderProps

Re-exports ExplorerContextProviderProps

ExplorerContextType

Re-exports ExplorerContextType

ExplorerFieldDef

Re-exports ExplorerFieldDef

ExplorerNavStack

Re-exports ExplorerNavStack

ExplorerNavStackItem

Re-exports ExplorerNavStackItem

ExplorerSection

Re-exports ExplorerSection

FieldDocumentation

Re-exports FieldDocumentation

FieldIcon

Re-exports FieldIcon

FieldLink

Re-exports FieldLink

GraphiQL

Re-exports GraphiQL

GraphiQLInterface

Re-exports GraphiQLInterface

GraphiQLInterfaceProps

Re-exports GraphiQLInterfaceProps

GraphiQLPlugin

Re-exports GraphiQLPlugin

GraphiQLProps

Re-exports GraphiQLProps

GraphiQLProvider

Re-exports GraphiQLProvider

GraphiQLProvider

Re-exports GraphiQLProvider

GraphiQLProviderProps

Re-exports GraphiQLProviderProps

GraphiQLProviderProps

Re-exports GraphiQLProviderProps

HISTORY_PLUGIN

Re-exports HISTORY_PLUGIN

History

Re-exports History

HistoryContext

Re-exports HistoryContext

HistoryContextProvider

Re-exports HistoryContextProvider

HistoryContextProviderProps

Re-exports HistoryContextProviderProps

HistoryContextType

Re-exports HistoryContextType

HistoryIcon

Re-exports HistoryIcon

ImagePreview

Re-exports ImagePreview

ImplementsIcon

Re-exports ImplementsIcon

KeyMap

Re-exports KeyMap

KeyboardShortcutIcon

Re-exports KeyboardShortcutIcon

Listbox

Re-exports Listbox

MagnifyingGlassIcon

Re-exports MagnifyingGlassIcon

MarkdownContent

Re-exports MarkdownContent

Menu

Re-exports Menu

MergeIcon

Re-exports MergeIcon

PenIcon

Re-exports PenIcon

PlayIcon

Re-exports PlayIcon

PluginContext

Re-exports PluginContext

PluginContextProvider

Re-exports PluginContextProvider

PluginContextProviderProps

Re-exports PluginContextProviderProps

PluginContextType

Re-exports PluginContextType

PlusIcon

Re-exports PlusIcon

PrettifyIcon

Re-exports PrettifyIcon

ReloadIcon

Re-exports ReloadIcon

ResponseTooltipType

Re-exports ResponseTooltipType

RootTypeIcon

Re-exports RootTypeIcon

SchemaContext

Re-exports SchemaContext

SchemaContextProvider

Re-exports SchemaContextProvider

SchemaContextProviderProps

Re-exports SchemaContextProviderProps

SchemaContextType

Re-exports SchemaContextType

SchemaDocumentation

Re-exports SchemaDocumentation

Search

Re-exports Search

SettingsIcon

Re-exports SettingsIcon

Spinner

Re-exports Spinner

StarFilledIcon

Re-exports StarFilledIcon

StarIcon

Re-exports StarIcon

StopIcon

Re-exports StopIcon

StorageContext

Re-exports StorageContext

StorageContextProvider

Re-exports StorageContextProvider

StorageContextProviderProps

Re-exports StorageContextProviderProps

StorageContextType

Re-exports StorageContextType

Tab

Re-exports Tab

Tabs

Re-exports Tabs

TabsState

Re-exports TabsState

Theme

Re-exports Theme

ToolbarButton

Re-exports ToolbarButton

ToolbarListbox

Re-exports ToolbarListbox

ToolbarMenu

Re-exports ToolbarMenu

Tooltip

Re-exports Tooltip

TypeDocumentation

Re-exports TypeDocumentation

TypeIcon

Re-exports TypeIcon

TypeLink

Re-exports TypeLink

UnStyledButton

Re-exports UnStyledButton

UseHeaderEditorArgs

Re-exports UseHeaderEditorArgs

UseQueryEditorArgs

Re-exports UseQueryEditorArgs

UseResponseEditorArgs

Re-exports UseResponseEditorArgs

UseVariableEditorArgs

Re-exports UseVariableEditorArgs

WriteableEditorProps

Re-exports WriteableEditorProps

default

Renames and re-exports GraphiQL

useAutoCompleteLeafs

Re-exports useAutoCompleteLeafs

useCopyQuery

Re-exports useCopyQuery

useDragResize

Re-exports useDragResize

useEditorContext

Re-exports useEditorContext

useExecutionContext

Re-exports useExecutionContext

useExplorerContext

Re-exports useExplorerContext

useHistoryContext

Re-exports useHistoryContext

useMergeQuery

Re-exports useMergeQuery

usePluginContext

Re-exports usePluginContext

usePrettifyEditors

Re-exports usePrettifyEditors

useSchemaContext

Re-exports useSchemaContext

useStorageContext

Re-exports useStorageContext

useTheme

Re-exports useTheme

Type aliases

GraphiQLInterfaceProps

GraphiQLInterfaceProps: WriteableEditorProps & AddSuffix<Pick<UseQueryEditorArgs, "onEdit">, "Query"> & Pick<UseQueryEditorArgs, "onCopyQuery"> & AddSuffix<Pick<UseVariableEditorArgs, "onEdit">, "Variables"> & AddSuffix<Pick<UseHeaderEditorArgs, "onEdit">, "Headers"> & Pick<UseResponseEditorArgs, "responseTooltip"> & { children?: ReactNode; defaultEditorToolsVisibility?: boolean | "variables" | "headers"; isHeadersEditorEnabled?: boolean; showPersistHeadersSettings?: boolean; toolbar?: GraphiQLToolbarConfig }

GraphiQLProps

GraphiQLProps: Omit<GraphiQLProviderProps, "children"> & GraphiQLInterfaceProps

GraphiQLToolbarConfig

GraphiQLToolbarConfig: { additionalContent?: React.ReactNode }

Type declaration

  • Optional additionalContent?: React.ReactNode

    This content will be rendered after the built-in buttons of the toolbar. Note that this will not apply if you provide a completely custom toolbar (by passing GraphiQL.Toolbar as child to the GraphiQL component).

Maybe

Maybe<T>: T | null | undefined

Type parameters

  • T

Op

Op: { headersString?: string; query: string; response?: Record<string, any>; variables?: Record<string, any>; variablesString?: string }

Type declaration

  • Optional headersString?: string
  • query: string
  • Optional response?: Record<string, any>
  • Optional variables?: Record<string, any>
  • Optional variablesString?: string

ReactComponentLike

ReactComponentLike: string | ((props: any, context?: any) => any) | {}

ReactElementLike

ReactElementLike: { key: string | number | null; props: any; type: ReactComponentLike }

Type declaration

ReactNodeLike

ReactNodeLike: {} | ReactElementLike | Array<ReactNodeLike> | string | number | boolean | null | undefined

Variables

Const DEFAULT_HEADERS

DEFAULT_HEADERS: "{"foo":2}" = "{"foo":2}"

Const testQuery

testQuery: "{longDescriptionType {idimagehasArgstest {idisTest__typename}}}" = `{longDescriptionType {idimagehasArgstest {idisTest__typename}}}`

Functions

CodeMirror

  • CodeMirror(node: HTMLElement, __namedParameters: { options: options; value: any }): { emit: _emit; getValue: any; off: any; on: any; setSize: any; setValue: any; options: object }

GraphiQL

  • GraphiQL(__namedParameters: { dangerouslyAssumeSchemaIsValid: boolean; defaultHeaders: string; defaultQuery: string; defaultTabs: TabDefinition[]; externalFragments: string | FragmentDefinitionNode[]; fetcher: Fetcher; getDefaultFieldNames: GetDefaultFieldNamesFn; headers: string; initialTabs: TabDefinition[]; inputValueDeprecation: boolean; introspectionQueryName: string; maxHistoryLength: number; onEditOperationName: onEditOperationName; onSchemaChange: onSchemaChange; onTabChange: onTabChange; onTogglePluginVisibility: onTogglePluginVisibility; operationName: string; plugins: GraphiQLPlugin[]; props: props; query: string; response: string; schema: GraphQLSchema | IntrospectionQuery; schemaDescription: boolean; shouldPersistHeaders: boolean; storage: Storage; validationRules: ValidationRule[]; variables: string; visiblePlugin: string | GraphiQLPlugin }): Element

GraphiQLInterface

Const HeaderEditor

  • HeaderEditor(props: HeaderEditorProps): Element

Const QueryEditor

Const ResponseEditor

  • ResponseEditor(): Element

Const VariableEditor

  • VariableEditor(props: VariableEditorProps): Element

codeWithLineNumbers

  • codeWithLineNumbers(code: string): string

normalize

  • normalize(str: string): any

normalizeWhitespace

  • normalizeWhitespace(str: string): any

Const useHeaderEditor

Const useQueryEditor

Const useResponseEditor

  • useResponseEditor(): MutableRefObject<HTMLDivElement>

Const useVariableEditor

Object literals

Const mockSuccess

mockSuccess: object

data

data: object

longDescriptionType

longDescriptionType: object

hasArgs

hasArgs: string = "{"defaultValue":"test default value"}"

id

id: string = "abc123"

image

image: string = "/images/logo.svg"

test

test: object

__typename

__typename: string = "Test"

id

id: string = "abc123"

isTest

isTest: boolean = true

Generated using TypeDoc