Sets the color theme you want to use for the editor.
Sets the key map to use when using the editor.
Sets the color theme you want to use for the editor.
Sets the key map to use when using the editor.
Headers to be set when opening a new tab
The initial contents of the query editor when loading GraphiQL and there is no other source for the editor state. Other sources can be:
query propThis prop can be used to define the default set of tabs, with their queries, variables, and headers. It will be used as default only if there is no tab state persisted in storage.
With this prop you can pass so-called "external" fragments that will be
included in the query document (depending on usage). You can either pass
the fragments using SDL (passing a string) or you can pass a list of
FragmentDefinitionNode objects.
This prop can be used to set the contents of the headers editor. Every time this prop changes, the contents of the headers editor are replaced. Note that the editor contents can be changed in between these updates by typing in the editor.
This prop can be used to set the contents of the query editor. Every time this prop changes, the contents of the query editor are replaced. Note that the editor contents can be changed in between these updates by typing in the editor.
This prop can be used to set the contents of the response editor. Every time this prop changes, the contents of the response editor are replaced. Note that the editor contents can change in between these updates by executing queries that will show a response.
This prop toggles if the contents of the headers editor are persisted in storage.
This prop accepts custom validation rules for GraphQL documents that are run against the contents of the query editor (in addition to the rules that are specified in the GraphQL spec).
This prop can be used to set the contents of the variables editor. Every time this prop changes, the contents of the variables editor are replaced. Note that the editor contents can be changed in between these updates by typing in the editor.
Invoked when the operation name changes. Possible triggers are:
The operation name after it has been changed.
Invoked when the state of the tabs changes. Possible triggers are:
The tabs state after it has been updated.
Headers to be set when opening a new tab
The initial contents of the query editor when loading GraphiQL and there is no other source for the editor state. Other sources can be:
query propThis prop can be used to define the default set of tabs, with their queries, variables, and headers. It will be used as default only if there is no tab state persisted in storage.
With this prop you can pass so-called "external" fragments that will be
included in the query document (depending on usage). You can either pass
the fragments using SDL (passing a string) or you can pass a list of
FragmentDefinitionNode objects.
This prop can be used to set the contents of the headers editor. Every time this prop changes, the contents of the headers editor are replaced. Note that the editor contents can be changed in between these updates by typing in the editor.
This prop can be used to set the contents of the query editor. Every time this prop changes, the contents of the query editor are replaced. Note that the editor contents can be changed in between these updates by typing in the editor.
This prop can be used to set the contents of the response editor. Every time this prop changes, the contents of the response editor are replaced. Note that the editor contents can change in between these updates by executing queries that will show a response.
This prop toggles if the contents of the headers editor are persisted in storage.
This prop accepts custom validation rules for GraphQL documents that are run against the contents of the query editor (in addition to the rules that are specified in the GraphQL spec).
This prop can be used to set the contents of the variables editor. Every time this prop changes, the contents of the variables editor are replaced. Note that the editor contents can be changed in between these updates by typing in the editor.
Invoked when the operation name changes. Possible triggers are:
The operation name after it has been changed.
Invoked when the state of the tabs changes. Possible triggers are:
The tabs state after it has been updated.
If there is currently a GraphQL request in-flight. For multi-part
requests like subscriptions, this will be true while fetching the
first partial response and false while fetching subsequent batches.
If there is currently a GraphQL request in-flight. For multi-part
requests like subscriptions, this will be true until the last batch
has been fetched or the connection is closed from the client.
The operation name that will be sent with all GraphQL requests.
Start a GraphQL requests based of the current editor contents.
Stop the GraphQL request that is currently in-flight.
If there is currently a GraphQL request in-flight. For multi-part
requests like subscriptions, this will be true while fetching the
first partial response and false while fetching subsequent batches.
If there is currently a GraphQL request in-flight. For multi-part
requests like subscriptions, this will be true until the last batch
has been fetched or the connection is closed from the client.
The operation name that will be sent with all GraphQL requests.
Start a GraphQL requests based of the current editor contents.
Stop the GraphQL request that is currently in-flight.
A stack of navigation items. The last item in the list is the current one. This list always contains at least one item.
Pop the last item from the navigation stack.
Push an item to the navigation stack.
The item that should be pushed to the stack.
Reset the navigation stack to its initial state, this will remove all but the initial stack item.
A stack of navigation items. The last item in the list is the current one. This list always contains at least one item.
Pop the last item from the navigation stack.
Push an item to the navigation stack.
The item that should be pushed to the stack.
Reset the navigation stack to its initial state, this will remove all but the initial stack item.
The definition object of the item, this can be a named type, a field, an input field or an argument.
The name of the item.
The definition object of the item, this can be a named type, a field, an input field or an argument.
The name of the item.
A component that renders content into the plugin pane.
A component that renders an icon that will be shown inside a button that toggles the plugin visibility.
The unique title of the plugin. If two plugins are present with the same title the provider component will throw an error.
A component that renders content into the plugin pane.
A component that renders an icon that will be shown inside a button that toggles the plugin visibility.
The unique title of the plugin. If two plugins are present with the same title the provider component will throw an error.
The maximum number of executed operations to store.
The maximum number of executed operations to store.
The list of history items.
Add an operation to the history.
The operation that was executed, consisting of the query, variables, headers, and operation name.
Delete an operation from the history.
The operation that was executed, consisting of the query, variables, headers, and operation name.
This is only if you press the 'clear' button
Change the custom label of an item from the history.
An object containing the label (undefined if it should be
unset) and properties that identify the history item that the label should
be applied to. (This can result in the label being applied to multiple
history items.)
Index to edit. Without it, will look for the first index matching the operation, which may lead to misleading results if multiple items have the same label
If you need to know when an item in history is set as active to customize your application.
Toggle the favorite state of an item from the history.
An object containing the favorite state (undefined if it
should be unset) and properties that identify the history item that the
label should be applied to. (This can result in the label being applied
to multiple history items.)
The list of history items.
Add an operation to the history.
The operation that was executed, consisting of the query, variables, headers, and operation name.
Delete an operation from the history.
The operation that was executed, consisting of the query, variables, headers, and operation name.
This is only if you press the 'clear' button
Change the custom label of an item from the history.
An object containing the label (undefined if it should be
unset) and properties that identify the history item that the label should
be applied to. (This can result in the label being applied to multiple
history items.)
Index to edit. Without it, will look for the first index matching the operation, which may lead to misleading results if multiple items have the same label
If you need to know when an item in history is set as active to customize your application.
Toggle the favorite state of an item from the history.
An object containing the favorite state (undefined if it
should be unset) and properties that identify the history item that the
label should be applied to. (This can result in the label being applied
to multiple history items.)
This props accepts a list of plugins that will be shown in addition to the built-in ones (the doc explorer and the history).
This prop can be used to set the visibility state of plugins. Every time
this prop changes, the visibility state will be overridden. Note that the
visibility state can change in between these updates, for example by
calling the setVisiblePlugin function provided by the context.
Invoked when the visibility state of any plugin changes.
The plugin object that is now visible. If no plugin
is visible, the function will be invoked with null.
This props accepts a list of plugins that will be shown in addition to the built-in ones (the doc explorer and the history).
This prop can be used to set the visibility state of plugins. Every time
this prop changes, the visibility state will be overridden. Note that the
visibility state can change in between these updates, for example by
calling the setVisiblePlugin function provided by the context.
Invoked when the visibility state of any plugin changes.
The plugin object that is now visible. If no plugin
is visible, the function will be invoked with null.
A list of all current plugins, including the built-in ones (the doc explorer and the history).
The plugin which is currently visible.
Defines the plugin which is currently visible.
The plugin that should become visible. You can either pass
the plugin object (has to be referentially equal to the one passed as
prop) or the plugin title as string. If null is passed, no plugin will
be visible.
A list of all current plugins, including the built-in ones (the doc explorer and the history).
The plugin which is currently visible.
Defines the plugin which is currently visible.
The plugin that should become visible. You can either pass
the plugin object (has to be referentially equal to the one passed as
prop) or the plugin title as string. If null is passed, no plugin will
be visible.
Stores an error raised during introspecting or building the GraphQL schema from the introspection result.
If there currently is an introspection request in-flight.
The current GraphQL schema.
A list of errors from validating the current GraphQL schema. The schema is valid if and only if this list is empty.
Trigger building the GraphQL schema. This might trigger an introspection
request if no schema is passed via props and if using a schema is not
explicitly disabled by passing null as value for the schema prop. If
there is a schema (either fetched using introspection or passed via props)
it will be validated, unless this is explicitly skipped using the
dangerouslyAssumeSchemaIsValid prop.
Stores an error raised during introspecting or building the GraphQL schema from the introspection result.
If there currently is an introspection request in-flight.
The current GraphQL schema.
A list of errors from validating the current GraphQL schema. The schema is valid if and only if this list is empty.
Trigger building the GraphQL schema. This might trigger an introspection
request if no schema is passed via props and if using a schema is not
explicitly disabled by passing null as value for the schema prop. If
there is a schema (either fetched using introspection or passed via props)
it will be validated, unless this is explicitly skipped using the
dangerouslyAssumeSchemaIsValid prop.
Provide a custom storage API.
Provide a custom storage API.
The contents of the headers editor of this tab.
The contents of the query editor of this tab.
The contents of the variable editor of this tab.
The contents of the headers editor of this tab.
The contents of the query editor of this tab.
The contents of the variable editor of this tab.
This object describes the state of a single tab.
This object describes the state of a single tab.
This object describes the state of all tabs.
The index of the currently active tab with regards to the tabs list of
this object.
A list of state objects for each tab.
This object describes the state of all tabs.
The index of the currently active tab with regards to the tabs list of
this object.
A list of state objects for each tab.
The value null semantically means that the user does not explicitly choose
any theme, so we use the system default.
The value null semantically means that the user does not explicitly choose
any theme, so we use the system default.
This is only meant to be used internally in @graphiql/react.
A function to determine which field leafs are automatically added when
trying to execute a query with missing selection sets. It will be called
with the GraphQLType for which fields need to be added.
This is only meant to be used internally in @graphiql/react.
A function to determine which field leafs are automatically added when
trying to execute a query with missing selection sets. It will be called
with the GraphQLType for which fields need to be added.
This is only meant to be used internally in @graphiql/react.
Invoked when the current contents of the query editor are copied to the clipboard.
This is only meant to be used internally in @graphiql/react.
Invoked when the current contents of the query editor are copied to the clipboard.
useState-like hook for current tab variables editor state
useState-like hook for current tab operations editor state
useState-like hook for current tab variables editor state
The functions send the entire operation so users can customize their own application with <HistoryContext.Provider value={customizedFunctions} /> and get access to the operation plus any additional props they added for their needs (i.e., build their own functions that may save to a backend instead of localStorage and might need an id property added to the QueryStoreItem)
The functions send the entire operation so users can customize their own application with <HistoryContext.Provider value={customizedFunctions} /> and get access to the operation plus any additional props they added for their needs (i.e., build their own functions that may save to a backend instead of localStorage and might need an id property added to the QueryStoreItem)
Provided a duration and a function, returns a new function which is called
duration milliseconds after the last call.
Provided a duration and a function, returns a new function which is called
duration milliseconds after the last call.
Dynamically import codemirror and dependencies This works for codemirror 5, not sure if the same imports work for 6
Dynamically import codemirror and dependencies This works for codemirror 5, not sure if the same imports work for 6
Render a custom UI for CodeMirror's hint which includes additional info about the type and description for the selected context.
Render a custom UI for CodeMirror's hint which includes additional info about the type and description for the selected context.
useState-like hook for current tab variables editor state
useState-like hook for current tab operations editor state
Implements an optimistic caching strategy around a useState-like hook in order to prevent loss of updates when the hook has an internal delay and the update function is called again before the updated state is sent out.
Use this as a wrapper around useOperationsEditorState,
useVariablesEditorState, or useHeadersEditorState if you anticipate
calling them with great frequency (due to, for instance, mouse, keyboard, or
network events).
Example:
const [operationsString, handleEditOperations] =
useOptimisticState(useOperationsEditorState());Implements an optimistic caching strategy around a useState-like hook in order to prevent loss of updates when the hook has an internal delay and the update function is called again before the updated state is sent out.
Use this as a wrapper around useOperationsEditorState,
useVariablesEditorState, or useHeadersEditorState if you anticipate
calling them with great frequency (due to, for instance, mouse, keyboard, or
network events).
Example:
const [operationsString, handleEditOperations] =
useOptimisticState(useOperationsEditorState());useState-like hook for current tab variables editor state
Generated using TypeDoc
Changelog | API Docs | NPM
@graphiql/reactA 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
GraphiQLProvidercomponent 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 methodcreateGraphiQLFetcherfrom the@graphiql/toolkitpackage.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.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/reactcan be found in the reference implementation of a GraphQL IDE - GraphiQL - in thegraphiqlpackage.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/reactStorageContext: Provides a storage API that can be used to persist state in the browser (by default usinglocalStorage)EditorContext: Manages all the editors and tabsSchemaContext: Fetches, validates and stores the GraphQL schemaExecutionContext: Executes GraphQL requestsHistoryContext: Persists executed requests in storageExplorerContext: Handles the state for the docs explorerAll 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/reacthave 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.cssfile.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/reactto use transparent colors by passing the value of the CSS variable in thehslafunction. 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/reactlocally - in particular when working on thegraphiqlpackage - all you need to do is runyarn devin the package folder in a separate terminal. This will build the package using Vite. When using it in combination withyarn dev-graphiql(running in the repo root) this will give you auto-reloading when working ongraphiqland@graphiql/reactsimultaneously.