Skip to main content

useSubscription

⚠️ NOTE: This document still needs to be updated for Apollo React/Relay Duct-Tape.

useSubscription​

Hook used to subscribe and unsubscribe to a subscription.

import {graphql, useSubscription} from 'react-relay';
import {useMemo} from 'react';

const subscription = graphql`
  subscription UserDataSubscription($input: InputData!) {
    # ...
  }
`;

function UserComponent({ id }) {
  // IMPORTANT: your config should be memoized.
  // Otherwise, useSubscription will re-render too frequently.
  const config = useMemo(() => ({
    variables: {id},
    subscription,
  }), [id, subscription]);

  useSubscription(config);

  return (/* ... */);
}

Arguments​

  • config: a config of type GraphQLSubscriptionConfig passed to requestSubscription
  • requestSubscriptionFn: ?<TSubscriptionPayload>(IEnvironment, GraphQLSubscriptionConfig<TSubscriptionPayload>) => Disposable. An optional function with the same signature as requestSubscription, which will be called in its stead. Defaults to requestSubscription.

Type GraphQLSubscriptionConfig<TSubscriptionPayload>​

  • An object with the following fields:
    • cacheConfig: [Optional] CacheConfig
    • subscription: GraphQLTaggedNode. A GraphQL subscription specified using a graphql template literal
    • variables: The variables to pass to the subscription
    • onCompleted: [Optional] () => void. An optional callback that is executed when the subscription is established
    • onError: [Optional] (Error) => {}. An optional callback that is executed when an error occurs
    • onNext: [Optional] (TSubscriptionPayload) => {}. An optional callback that is executed when new data is received
    • updater: [Optional] SelectorStoreUpdater.

Flow Type Parameters​

  • TSubscriptionPayload: The type of the payloads vended by the subscription. You should pass the flow type imported from the auto-generated .graphql file corresponding to the subscription, e.g. use UserDataSubscription as the type parameter, from import type {UserDataSubscription} from './__generated__/UserDataSubscription.graphql';

Behavior​

  • This is only a thin wrapper around the requestSubscription API. It will:
    • Subscribe when the component is mounted with the given config
    • Unsubscribe when the component is unmounted
    • Unsubscribe and resubscribe with new values if the environment, config or requestSubscriptionFn changes.
  • If you have the need to do something more complicated, such as imperatively requesting a subscription, please use the requestSubscription API directly.
  • See the GraphQL Subscriptions Guide for a more detailed explanation of how to work with subscriptions.