@graphiql/react

What is @graphiql/react?

@graphiql/react is a React component library for building GraphiQL interfaces. It provides a set of React components that can be used to create a GraphQL IDE within your React application, allowing for easy querying, mutation, and schema exploration.

What are @graphiql/react's main functionalities?

GraphiQL Component

This code demonstrates how to use the GraphiQL component from @graphiql/react to create a GraphQL IDE within a React application. The fetcher function is used to send GraphQL queries to a specified endpoint.

import React from 'react';
import { GraphiQL } from '@graphiql/react';
import '@graphiql/react/dist/style.css';

const App = () => (
  <div style={{ height: '100vh' }}>
    <GraphiQL fetcher={async graphQLParams => {
      const data = await fetch('https://my-graphql-endpoint.com/graphql', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(graphQLParams),
      });
      return data.json();
    }} />
  </div>
);

export default App;

Custom Toolbar

This code demonstrates how to add a custom toolbar button to the GraphiQL interface. The CustomToolbar component includes a ToolbarButton that triggers an alert when clicked.

import React from 'react';
import { GraphiQL, ToolbarButton } from '@graphiql/react';
import '@graphiql/react/dist/style.css';

const CustomToolbar = () => (
  <GraphiQL.Toolbar>
    <ToolbarButton onClick={() => alert('Custom Button Clicked!')} title="Custom Button" />
  </GraphiQL.Toolbar>
);

const App = () => (
  <div style={{ height: '100vh' }}>
    <GraphiQL fetcher={async graphQLParams => {
      const data = await fetch('https://my-graphql-endpoint.com/graphql', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(graphQLParams),
      });
      return data.json();
    }}>
      <CustomToolbar />
    </GraphiQL>
  </div>
);

export default App;

Custom Query Editor

This code demonstrates how to use a custom query editor within the GraphiQL interface. The CustomQueryEditor component initializes the query editor with a default query and logs any changes to the console.

import React from 'react';
import { GraphiQL, QueryEditor } from '@graphiql/react';
import '@graphiql/react/dist/style.css';

const CustomQueryEditor = () => (
  <QueryEditor value="{ hello }" onEdit={newQuery => console.log(newQuery)} />
);

const App = () => (
  <div style={{ height: '100vh' }}>
    <GraphiQL fetcher={async graphQLParams => {
      const data = await fetch('https://my-graphql-endpoint.com/graphql', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(graphQLParams),
      });
      return data.json();
    }}>
      <CustomQueryEditor />
    </GraphiQL>
  </div>
);

export default App;

Other packages similar to @graphiql/react

graphiql

GraphiQL is the original GraphQL IDE created by the GraphQL Foundation. It provides a web-based interface for exploring GraphQL queries and mutations. While @graphiql/react is a React component library, graphiql is a standalone application that can be embedded in web applications.

altair

Altair is a feature-rich GraphQL client that provides a web-based interface for testing and exploring GraphQL queries. It offers features like query history, variable extraction, and more. Unlike @graphiql/react, Altair is not a React component library but a standalone application.

apollo-client-devtools

Apollo Client Devtools is a browser extension for Chrome and Firefox that provides a GraphQL IDE for Apollo Client. It allows developers to inspect queries, mutations, and the Apollo Client cache. Unlike @graphiql/react, it is not a React component library but a browser extension.

README

Changelog | API Docs | NPM

@graphiql/react

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

Purpose

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.

Getting started

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.

There is one required prop called fetcher. This is a function that performs GraphQL request against a given endpoint. You can easily create a fetcher using the method createGraphiQLFetcher from the @graphiql/toolkit package.

import { GraphiQLProvider } from '@graphiql/react';
import { createGraphiQLFetcher } from '@graphiql/toolkit';

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

function MyGraphQLIDE() {
  return (
    <GraphiQLProvider fetcher={fetcher}>
      <div className="graphiql-container">Hello GraphQL</div>
    </GraphiQLProvider>
  );
}

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

import { QueryEditor } from '@graphiql/react';

function MyGraphQLIDE() {
  return (
    <GraphiQLProvider fetcher={fetcher}>
      <div className="graphiql-container">
        <QueryEditor />
      </div>
    </GraphiQLProvider>
  );
}

The package also ships the necessary CSS that all its UI components need. You can import them from @graphiql/react/dist/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.

Available contexts

There are multiple contexts that own different parts of the state that make up a complete GraphQL IDE. For each context there is a provider component (<name>ContextProvider) that makes sure the context is initialized and managed properly. These components contains all the logic related to state management. In addition, for each context there is also a hook (use<name>Context) that allows you to consume its current value.

Here is a list of all contexts that come with @graphiql/react

• StorageContext: Provides a storage API that can be used to persist state in the browser (by default using localStorage)
• EditorContext: Manages all the editors and tabs
• SchemaContext: Fetches, validates and stores the GraphQL schema
• ExecutionContext: Executes GraphQL requests
• HistoryContext: Persists executed requests in storage
• ExplorerContext: Handles the state for the docs explorer

All context properties are documented using JSDoc 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.

Theming

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

All variables that are available for customization can be found in the root.css file.

Colors

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 allows @graphiql/react to use transparent colors by passing the value of the CSS variable in the hsla function. This enables us to provide truly reusable UI elements where good contrasts are preserved regardless of the elements background.

Development

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