graphiql
Version:
An graphical interactive in-browser GraphQL IDE.
262 lines (196 loc) • 10.6 kB
Markdown
# 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](https://github.com/graphql/graphiql/tree/main/docs/security/2021-introspection-schema-xss.md).
[](https://npmjs.com/graphiql)
[](LICENSE)
[](https://discord.gg/NP5vbPeUFp)
_/ˈɡrafək(ə)l/_ A graphical interactive in-browser GraphQL IDE.
[Try the live demo](https://graphql.org/swapi-graphql).
[](https://graphql.org/swapi-graphql)
## Features
- Full language support of the latest
[GraphQL Specification](https://spec.graphql.org/draft/#sec-Language):
- 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
- The [latest stable version](https://graphql.org/swapi-graphql)
- The current state of the `main` branch:
- An [installable PWA](https://graphiql-test.netlify.com/webpack) with plugins ([source](../../examples//graphiql-webpack))
- Using the [minified bundles](https://graphiql-test.netlify.com)
- Using the [development bundles](https://graphiql-test.netlify.com/dev) (good
for inspecting, debugging, etc)
- Each pull request will also get its own preview deployment on Netlify, you'll
find a link in the GitHub checks
## Examples
- [`CDN`](../../examples/graphiql-cdn) - A single HTML file that loads GraphiQL directly from a CDN
- [`Webpack`](../../examples/graphiql-webpack) - A starter for Webpack
- [`Create React App`](../../examples/graphiql-create-react-app) - An example
using [Create React App](https://create-react-app.dev)
- [`Parcel`](../../examples/graphiql-parcel) - An example using
[Parcel](https://parceljs.org)
## Getting started
- [Migration guide to GraphiQL 2](../../docs/migration/graphiql-2.0.0.md)
- [Migration guide to GraphiQL 4](../../docs/migration/graphiql-4.0.0.md)
- [Migration guide to GraphiQL 5](../../docs/migration/graphiql-5.0.0.md)
- [Migration guide to GraphiQL 6](../../docs/migration/graphiql-6.0.0.md)
### CDN usage
To use GraphiQL without a bundler, follow the [CDN example](../../examples/graphiql-cdn).
## 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`.
```sh
npm install 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
The `GraphiQL` component needs to know how to run operations against a GraphQL
API, which it gets from either a `transport` or a `fetcher` prop (the two are
mutually exclusive). A `transport` is an object with a `send(request)` method
that performs the request. `send` may return a `Promise` for queries or
mutations, or an `AsyncIterable` for subscriptions and multipart responses.
An easy way to create one is the
[`createTransport`](../graphiql-toolkit/src/create-transport/createTransport.ts)
function exported from the `@graphiql/toolkit` package. If you want to
implement your own transport, you can use the `Transport` type from
`@graphiql/toolkit` to make sure the shape matches what GraphiQL expects.
`fetcher` is still supported — it's deprecated but not removed, and predates
`transport`. Unlike a `transport`, a `fetcher` is a plain function that returns
an execution result directly, with no access to the underlying HTTP response.
See the [v6 migration guide](../../docs/migration/graphiql-6.0.0.md#new-transport-api)
if you're moving from `fetcher` to `transport`.
The following is everything you need to render GraphiQL in your React
application:
```jsx
import { createTransport } from '@graphiql/toolkit';
import { GraphiQL } from 'graphiql';
import { createRoot } from 'react-dom/client';
import 'graphiql/style.css';
const transport = createTransport({ url: 'https://my.backend/graphql' });
const root = createRoot(document.getElementById('root'));
root.render(<GraphiQL transport={transport} />);
```
When the connected server supports GraphQL.js 17 fragment arguments, opt in
with `<GraphiQL fetcher={fetcher} experimentalFragmentArguments />`. The syntax
is disabled by default.
## Customize
GraphiQL supports customization in UI and behavior by accepting React props and
children.
### Props
For props documentation, see the
[API Docs](https://graphiql-test.netlify.app/typedoc/modules/graphiql.html#graphiqlprops-1)
### Children
Parts of the UI can be customized by passing children to the `GraphiQL` or the
`GraphiQLInterface` component.
- `<GraphiQL.Footer>`: Add a custom footer shown below the response editor.
Branding and toolbar customization moved off the children API in `graphiql@6`:
- Replace the top bar's default hexagon icon + "GraphiQL" wordmark with the
`brand` prop, e.g. `<GraphiQL brand="My Company" />`.
- Add custom toolbar buttons through a plugin's `sessionActions`, which renders
into the tab strip alongside prettify/merge/copy/save. See the
[v6 migration guide](../../docs/migration/graphiql-6.0.0.md) for details.
### Plugins
Starting with `graphiql@2` there exists a simple plugin API that allows you to
build your own custom tools right into GraphiQL.
GraphiQL includes the History, Query Builder, and Collections plugins by
default. The documentation explorer is the default reference plugin. These 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. Doing so replaces the default list. Start with the immutable
`DEFAULT_PLUGINS` export when adding or removing a plugin so you don't need to
import the built-in plugin packages directly:
```jsx
import { DEFAULT_PLUGINS, GraphiQL } from 'graphiql';
const plugins = [...DEFAULT_PLUGINS, myPlugin];
<GraphiQL plugins={plugins} transport={transport} />;
```
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`.
### Theming
The GraphiQL interface uses CSS variables for theming, in particular for colors.
As of v6 the supported set is the OKLCH design tokens in
[`tokens.css`](../graphiql-react/src/style/tokens.css); the older `--color-*` HSL
variables in [`root.css`](../graphiql-react/src/style/root.css) are deprecated
(see the [v6 migration guide](../../docs/migration/graphiql-6.0.0.md#css-and-retheming)).
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 query, variables, headers, and response editors are built on
[Monaco](https://microsoft.github.io/monaco-editor/), so editor theming goes
through Monaco's theme system, not CSS. The `editorTheme` prop takes a
`{ dark, light }` pair of Monaco theme names, one for each GraphiQL theme:
```jsx
<GraphiQL editorTheme={{ dark: 'graphiql-DARK', light: 'graphiql-LIGHT' }} />
```
`graphiql-DARK` and `graphiql-LIGHT` are the built-in themes and also the
default value, so you only need to pass `editorTheme` if you want something
else. To use your own colors, register a theme with Monaco's `editor.defineTheme`
API before rendering `GraphiQL`, then reference it by name:
```jsx
import * as monaco from 'monaco-editor';
monaco.editor.defineTheme('my-dark-theme', {
base: 'vs-dark',
inherit: true,
rules: [],
colors: {},
});
// When rendering GraphiQL:
<GraphiQL editorTheme={{ dark: 'my-dark-theme', light: 'graphiql-LIGHT' }} />;
```
## Usage with a Custom Storage Namespace
When multiple GraphiQL instances run on the same origin—such as in different apps or
environments—they can conflict by reading from and writing to the same `localStorage` keys. To
prevent this, you can provide a custom `storage` object that prefixes all keys with a unique
namespace, isolating each instance’s state and avoiding collisions.
```tsx
import type { FC } from 'react';
import { GraphiQL } from 'graphiql';
import { createTransport } from '@graphiql/toolkit';
const transport = createTransport({ url: 'https://my.backend/graphql' });
const NAMESPACE = 'my-namespace';
const storage: typeof localStorage = {
...localStorage,
getItem(key) {
return localStorage.getItem(`${NAMESPACE}:${key}`);
},
setItem(key, value) {
return localStorage.setItem(`${NAMESPACE}:${key}`, value);
},
removeItem(key) {
return localStorage.removeItem(`${NAMESPACE}:${key}`);
},
};
export const App: FC = () => {
return <GraphiQL transport={transport} storage={myStorage} />;
};
```