Hooks (experimental)

Apollo Client experimental react hooks API reference

⚠️ The useFragment_experimental hook is currently at the preview stage in Apollo Client and is available by installing @apollo/client@beta. If you have feedback on it, please let us know via GitHub issues.

Beginning with version 3.7.0, Apollo Client Web has preview support for the useFragment_experimental hook, which represents a lightweight live binding into the Apollo Client Cache. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. useFragment_experimental never triggers network requests of its own.

useFragment_experimental enables Apollo Client to broadcast very specific fragment results to individual components. Note that the useQuery hook remains the primary hook responsible for querying and populating data in the cache (see the API reference). As a result, the component reading the fragment data via useFragment_experimental is still subscribed to all changes in the query data, but receives updates only when that fragment's specific data change.

Using `useFragment_experimental`

A GraphQL fragment is a piece of logic that can be shared between multiple queries and mutations. See the API reference.

Given the following fragment definition:

1
const ItemFragment = gql`
2
  fragment ItemFragment on Item {
3
    text
4
  }
5
`;

We can first use the useQuery hook to retrieve a list of items with ids.

1
const listQuery = gql`
2
  query {
3
    list {
4
      id
5
    }
6
  }
7
`;
8
function List() {
9
  const { loading, data } = useQuery(listQuery);
10
  return (
11
    <ol>
12
      {data?.list.map(item => <Item key={item.id} id={item.id}/>)}
13
    </ol>
14
  );
15
}

We can then use useFragment_experimental from within the <Item> component to create a live binding for each item by providing the fragment document, fragmentName and object reference via from.

1
function Item(props: { id: number }) {
2
  const { complete, data } = useFragment_experimental({
3
    fragment: ItemFragment,
4
    fragmentName: "ItemFragment",
5
    from: {
6
      __typename: "Item",
7
      id: props.id,
8
    },
9
  });
10
  return <li>{complete ? data!.text : "incomplete"}</li>;
11
}

`useFragment_experimental` API

Supported options and result fields for the useFragment_experimental hook are listed below.

Most calls to useFragment_experimental can omit the majority of these options, but it's useful to know they exist.

Options

The useFragment_experimental hook accepts the following options:

Name / Type	Description
Operation options
`from` `string \| StoreObject \| Reference`	Required. An object containing a `__typename` and primary key fields (such as `id`) identifying the entity object from which the fragment will be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID (uncommon).
`fragment` `DocumentNode`	Required. A GraphQL fragment document parsed into an AST with the `gql` template literal.
`fragmentName` `string`	The name of the fragment defined in the `fragment` document to use in the call. Required if the `fragment` document includes more than one fragment, optional otherwise.
`optimistic` `boolean`	If `true`, `readFragment` returns optimistic results. The default value is `true`.
`variables` `{ [key: string]: any }`	An object containing all of the GraphQL variables your fragment requires. Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
`returnPartialData` `boolean`	If `true`, the query can return partial results from the cache if the cache doesn't contain results for all queried fields. The default value is `true`.
`canonizeResults` `boolean`	If `true`, result objects read from the cache will be canonized, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results. The default value is `false`.

Result

Name / Type	Description
Operation result
`data` `TData`	An object containing the data for a given GraphQL fragment. This value might be `undefined` if a query results in one or more errors (depending on the query's `errorPolicy`).
`complete` `boolean`	A boolean indicating whether the data returned for the fragment is complete. When `false`, the `missing` field should explain which fields were responsible for the incompleteness.
`missing` `MissingTree`	A tree of all `MissingFieldError` messages reported during fragment reading, where the branches of the tree indicate the paths of the errors within the query result.

Edit on GitHub

Hooks

Testing

Hooks (experimental)

Apollo Client experimental react hooks API reference

`useFragment_experimental`

Installation

Using `useFragment_experimental`

`useFragment_experimental` API

Options

`from`

`fragment`

`fragmentName`

`optimistic`

`variables`

`returnPartialData`

`canonizeResults`

Result

`data`

`complete`

`missing`