DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/graphql-react package

    18.0.0 • Public • Published

    graphql-react logo


    npm version CI status

    A GraphQL client for React using modern context and hooks APIs that’s lightweight (< 4 kB) but powerful; the first Relay and Apollo alternative with server side rendering.

    The exports can also be used to custom load, cache and server side render any data, even from non-GraphQL sources.


    First, polyfill any required globals (see Requirements) that are missing in your server and client environments.

    Next.js setup

    See the next-graphql-react setup instructions.

    Custom React setup

    To install with npm, run:

    npm install graphql-react

    Create a single Cache instance and use the Provider component to provide it for your app.

    To server side render your app, use the waterfallRender function from react-waterfall-render.


    Here is a basic example using the GitHub GraphQL API, with tips commented:

    import useAutoLoad from "graphql-react/useAutoLoad.mjs";
    import useCacheEntry from "graphql-react/useCacheEntry.mjs";
    import useLoadGraphQL from "graphql-react/useLoadGraphQL.mjs";
    import useWaterfallLoad from "graphql-react/useWaterfallLoad.mjs";
    import React from "react";
    // The query is just a string; no need to use `gql` from `graphql-tag`. The
    // special comment before the string allows editor syntax highlighting, Prettier
    // formatting and linting. The cache system doesn’t require `__typename` or `id`
    // fields to be queried.
    const query = /* GraphQL */ `
      query ($repoId: ID!) {
        repo: node(id: $repoId) {
          ... on Repository {
            stargazers {
    export default function GitHubRepoStars({ repoId }) {
      const cacheKey = `GitHubRepoStars-${repoId}`;
      const cacheValue = useCacheEntry(cacheKey);
      // A hook for loading GraphQL is available, but custom hooks for loading non
      // GraphQL (e.g. fetching from a REST API) can be made.
      const loadGraphQL = useLoadGraphQL();
      const load = React.useCallback(
        () =>
          // To be DRY, utilize a custom hook for each API your app loads from, e.g.
          // `useLoadGraphQLGitHub`.
            // Fetch URI.
            // Fetch options.
              method: "POST",
              headers: {
                "Content-Type": "application/json",
                Accept: "application/json",
                Authorization: `Bearer ${process.env.GITHUB_ACCESS_TOKEN}`,
              body: JSON.stringify({
                variables: {
        [cacheKey, loadGraphQL, repoId]
      // This hook automatically keeps the cache entry loaded from when the
      // component mounts, reloading it if it’s staled or deleted. It also aborts
      // loading if the arguments change or the component unmounts; very handy for
      // auto-suggest components!
      useAutoLoad(cacheKey, load);
      // Waterfall loading can be used to load data when server side rendering,
      // enabled automagically by `next-graphql-react`. To learn how this works or
      // to set it up for a non-Next.js app, see:
      const isWaterfallLoading = useWaterfallLoad(cacheKey, load);
      // When waterfall loading it’s efficient to skip rendering, as the app will
      // re-render once this step of the waterfall has loaded. If more waterfall
      // loading happens in children, those steps of the waterfall are awaited and
      // the app re-renders again, and so forth until there’s no more loading for
      // the final server side render.
      return isWaterfallLoading
        ? null
        : cacheValue
        ? cacheValue.errors
          ? // Unlike many other GraphQL libraries, detailed loading errors are
            // cached and can be server side rendered without causing a
            // server/client HTML mismatch error.
        : // In this situation no cache value implies loading. Use the
          // `useLoadingEntry` hook to manage loading in detail.


    • Node.js: ^12.22.0 || ^14.17.0 || >= 16.0.0
    • Browsers: > 0.5%, not OperaMini all, not IE > 0, not dead

    Consider polyfilling:


    These ECMAScript modules are published to npm and exported via the package.json exports field:


    npm i graphql-react

    DownloadsWeekly Downloads






    Unpacked Size

    64.8 kB

    Total Files


    Last publish


    • jaydenseric