useFragmentHandle

Like useFragment, but also returns an imperative handle. Use this when the fragment is paginated or you need to trigger a refetch.

import { graphql, useFragmentHandle } from '$houdini'
import type { ShowList_show } from '$houdini'

export function ShowList({ show }: { show: ShowList_show }) {
  const { data, loadNext, loadNextPending, pageInfo } = useFragmentHandle(show, graphql(`
    fragment ShowList_show on Show @paginate {
      episodes(first: 10) @paginate {
        edges {
          node { title }
        }
      }
    }
  `))

  return (
    <>
      {data?.episodes.edges.map(({ node }) => <div key={node.title}>{node.title}</div>)}
      {pageInfo?.hasNextPage && (
        <button onClick={() => loadNext(10)} disabled={loadNextPending}>
          Load more
        </button>
      )}
    </>
  )
}

Refetch

When the fragment is marked with @refetchable, the handle also carries a refetch method that re-runs the fragment with new argument values:

import { graphql, useFragmentHandle } from '$houdini'
import type { UserInfo } from '$houdini'

export function UserInfo({ user }: { user: UserInfo }) {
  const { data, refetch } = useFragmentHandle(user, graphql(`
    fragment UserInfo on User @refetchable @arguments(filter: { type: "String" }) {
      friends(filter: $filter) {
        name
      }
    }
  `))

  return <button onClick={() => refetch({ filter: 'aki' })}>filter</button>
}

We only pass the arguments we want to change; the record’s id is derived from the data on screen. See Refetchable Fragments for the details.

Signature

function useFragmentHandle(reference, document): handle

Returns the same DocumentHandle shape as useQueryHandle: data, fetch, variables, plus pagination methods if the fragment uses @paginate, or a refetch method if it uses @refetchable.