Skip to main content
Version: Next 🚧

useSubscription

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.

Type CacheConfig​

  • An object with the following fields:
    • force: [Optional] A boolean. If true, causes a query to be issued unconditionally, regardless of the state of any configured response cache.
    • poll: [Optional] A number. Causes a query to live-update by polling at the specified interval, in milliseconds. (This value will be passed to setTimeout).
    • liveConfigId: [Optional] A string. Causes a query to live-update by calling GraphQLLiveQuery; it represents a configuration of gateway when doing live query.
    • metadata: [Optional] An object. User-supplied metadata.
    • transactionId: [Optional] A string. A user-supplied value, intended for use as a unique id for a given instance of executing an operation.

Type SelectorStoreUpdater​

  • A function with signature (store: RecordSourceSelectorProxy, data) => void
  • This interface allows you to imperatively write and read data directly to and from the Relay store. This means that you have full control over how to update the store in response to the subscription payload: you can create entirely new records, or update or delete existing ones. The full API for reading and writing to the Relay store is available here.

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.
Is this page useful?

Help us make the site even better by answering a few quick questions.