Variables
Const DEFAULT_HEADERS
DEFAULT_HEADERS: "{"foo":2}" = "{"foo":2}"
Let describeOrSkip
describeOrSkip: SuiteFunction | PendingSuiteFunction = describe
Const mockBadQuery
mockBadQuery: "bad {} query" = "bad {} query"
Const mockHeaders1
mockHeaders1: string = JSON.stringify({ foo: 'bar' })
Const mockHeaders2
mockHeaders2: string = JSON.stringify({ foo: 'baz' })
Const mockHistoryLabel1
mockHistoryLabel1: "Test" = "Test"
Const mockOperationName1
mockOperationName1: "Test" = "Test"
Const mockOperationName2
mockOperationName2: "Test2" = "Test2"
Const mockQuery1
mockQuery1: "query Test($string: String) {test {hasArgs(string: $string)}}" = `query Test($string: String) {test {hasArgs(string: $string)}}`
Const mockQuery2
mockQuery2: "query Test2 {test {id}}" = `query Test2 {test {id}}`
Const mockVariables1
mockVariables1: string = JSON.stringify({ string: 'string' })
Const mockVariables2
mockVariables2: string = JSON.stringify({ string: 'string2' })
Const testQuery
testQuery: "{longDescriptionType {idimagehasArgstest {idisTest__typename}}}" = `{longDescriptionType {idimagehasArgstest {idisTest__typename}}}`
GraphiQL
/ˈɡrafək(ə)l/ A graphical interactive in-browser GraphQL IDE. Try the live demo.
Features
localStorage
Live Demos
main
branch:Examples
Unpkg (CDN)
- A single HTML file using CDN assets and a script tagWebpack
- A starter for WebpackCreate React App
- An example using Create React AppParcel
- An example using ParcelGetting started
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 havereact
,react-dom
andgraphql
installed which are peer dependencies ofgraphiql
.The package exports a bunch of React components:
GraphiQLProvider
components renders multiple context providers that encapsulate all state managementGraphiQLInterface
component renders the UI that makes up GraphiQLGraphiQL
component is a combination of both the above componentsThere 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 aPromise
for queries or mutations, but also anObservable
or anAsyncIterable
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 theFetcher
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 { createRoot } from 'react-dom/client'; import 'graphiql/graphiql.css'; const fetcher = createGraphiQLFetcher({ url: 'https://my.backend/graphql' }); const root = createRoot(document.getElementById('root')); root.render(<GraphiQL fetcher={fetcher} />);
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 theGraphiQLInterface
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 allows 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 sidebarcontent
: A React component that renders the plugin contents which will be shown next to the sidebar when opening the pluginYou can pass a list of plugin objects to the
GraphiQL
component using theplugins
prop. You can also control the visibility state of plugins using thevisiblePlugin
prop and react to changes of the plugin visibility state using theonTogglePluginVisibility
prop.Inside the component you pass to
content
you can interact with the GraphiQL state using the hooks provided by@graphiql/react
. For 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.