$ npm install 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.
Breaking Changes & Improvements: several interfaces are being dropped for new ones for GraphiQL 2.0.0! Read more in this issue
graphiql@2.0.0-beta
is a much larger ongoing effort that introduces plugins, i18n, and so many more features after a substantial rewrite using modern react.
Discord Channel /ˈɡrafək(ə)l/ A graphical interactive in-browser GraphQL IDE. Try the live demo.
We have a few demos of master
branch via the default netlify build (the same URL paths apply to deploy previews on PRs):
graphiql.min.js
demo - the min.js bundle for the current refgraphiql.js
demo - development build is nice for react inspector, debugging, etcUnpkg (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 ParcelRollup
- TODOYou can use the graphiql
module, however bear in mind that react
react-dom
and graphql
will all need to be present already for it to work, as they are peerDependencies
With npm
:
npm install --save graphiql react react-dom graphql
Alternatively, if you are using yarn
:
yarn add graphiql react react-dom graphql
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)
Build for the web with webpack or browserify, or use the pre-bundled graphiql.js
file. See the cdn example in the git repository to see how to use the pre-bundled file, or see the webpack example to see how to bundle an application using the GraphiQL
component.
Note: If you are having webpack issues or questions about webpack, make sure you've cross-referenced your webpack configuration with our own webpack example first. We now have tests in CI that ensure this always builds, and we ensure it works end-to-end with every publish.
Using another GraphQL service? Here's how to get GraphiQL set up:
GraphiQL provides a React component responsible for rendering the UI, which should be provided with a required `fetcher function for executing GraphQL operations against your schema.
For HTTP transport implementations, we recommend using the fetch standard API, but you can use anything that matches the type signature, including async iterables and observables.
You can also install @graphiql/create-fetcher
to make it easier to create a simple fetcher for conventional http and websockets transports. It uses graphql-ws@4.x
protocol by default.
import React from 'react';
import ReactDOM from 'react-dom';
import GraphiQL from 'graphiql';
import { createGraphiQLFetcher } from '@graphiql/toolkit';
const fetcher = createGraphiQLFetcher({
url: window.location.origin + '/graphql',
});
ReactDOM.render(
<GraphiQL fetcher={fetcher} editorTheme={'dracula'} />,
document.body,
);
Read more about using createGraphiQLFetcher
in the readme to learn how to add headers, support the legacy subscriptions-transport-ws
protocol, and more.
Don't forget to include the CSS file on the page! If you're using npm
or yarn
, you can find it in node_modules/graphiql/graphiql.css
, or you can download it from the releases page.
For an example of setting up a GraphiQL, check out the example in this repository which also includes a few useful features highlighting GraphiQL's API.
The most minimal way to set up GraphiQL is a single index.html file:
<html>
<head>
<title>Simple GraphiQL Example</title>
<link href="https://unpkg.com/graphiql/graphiql.min.css" rel="stylesheet" />
</head>
<body style="margin: 0;">
<div id="graphiql" style="height: 100vh;"></div>
<script
crossorigin
src="https://unpkg.com/react/umd/react.production.min.js"
></script>
<script
crossorigin
src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"
></script>
<script
crossorigin
src="https://unpkg.com/graphiql/graphiql.min.js"
></script>
<script>
const fetcher = GraphiQL.createFetcher({ url: 'https://my/graphql' });
ReactDOM.render(
React.createElement(GraphiQL, { fetcher: fetcher }),
document.getElementById('graphiql'),
);
</script>
</body>
</html>
Notes:
React.createElement
directly is laborious, so follow the webpack instructions above for more highly customized implementationGraphiQL.createFetcher
in the UMD bundle only, so that it can be tree shaken out for modulesYou may be using a runtime that already provides graphiql, or that provides it via a middleware. For example, we support express-graphql
!
I would suggest a search for "graphiql <my runtime>" such as "graphiql express", "graphiql absinthe", etc to learn a potentially simpler route to setup for your environment. There are many npm packages, ruby gems, java utilities for deploying graphiql.
Here are some example searches:
This doesn't include runtimes or libraries where GraphiQL is used but isn't referenced in the package registry search entry.
GraphiQL supports customization in UI and behavior by accepting React props and children.
fetcher
is the only required prop for <GraphiQL />
.
For props documentation, see the API Docs
<GraphiQL.Logo>
: Replace the GraphiQL logo with your own.
<GraphiQL.Toolbar>
: Add a custom toolbar above GraphiQL. If not provided, a
default toolbar may contain common operations. Pass the empty
<GraphiQL.Toolbar />
if an empty toolbar is desired.
<GraphiQL.Button>
: Add a button to the toolbar above GraphiQL.
<GraphiQL.Menu>
: Add a dropdown menu to the toolbar above GraphiQL.
<GraphiQL.MenuItem>
: Items for a menu.<GraphiQL.Select>
: Add a select list to the toolbar above GraphiQL.
<GraphiQL.SelectOption>
: Options for a select list.<GraphiQL.Group>
: Add a group of associated controls to the
toolbar above GraphiQL. Expects children to be <GraphiQL.Button>
,
<GraphiQL.Menu>
, or <GraphiQL.Select>
.
<GraphiQL.Footer>
: Add a custom footer below GraphiQL Results.
TODO: kitchen sink example project or codesandbox
In order to theme the editor portions of the interface, you can supply a editorTheme
prop. You'll also need to load the appropriate CSS for the theme (similar to loading the CSS for this project). See the themes available here.
// In your html
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.23.0/theme/solarized.css" />
// In your GraphiQL JSX
<GraphiQL
editorTheme="solarized light"
/>
© 2010 - cnpmjs.org x YWFE | Home | YWFE