Hooks (experimental)
Apollo Client experimental react hooks API reference
useFragment_experimental
Installation
⚠️ The useFragment_experimental
hook is currently at the preview stage in Apollo Client. 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:
const ItemFragment = gql`fragment ItemFragment on Item {text}`;
We can first use the useQuery
hook to retrieve a list of items with id
s.
const listQuery = gql`query {list {id}}`;function List() {const { loading, data } = useQuery(listQuery);return (<ol>{data?.list.map(item => <Item key={item.id} id={item.id}/>)}</ol>);}
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
.
function Item(props: { id: number }) {const { complete, data } = useFragment_experimental({fragment: ItemFragment,fragmentName: "ItemFragment",from: {__typename: "Item",id: props.id,},});return <li>{complete ? data!.text : "incomplete"}</li>;}
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 | |
| Required. An object containing a |
| Required. A GraphQL fragment document parsed into an AST with the |
| The name of the fragment defined in the Required if the |
| If The default value is |
| 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. |
| If The default value is |
| If The default value is |
Result
Name / Type | Description |
---|---|
Operation result | |
| An object containing the data for a given GraphQL fragment. This value might be |
| A boolean indicating whether the data returned for the fragment is complete. When |
| A tree of all |