Skip to main content
Version: v13.0.0

Rendering Connections

In Relay, in order to display a list of data that is backed by a GraphQL connection, first you need to declare a fragment that queries for a connection:

const {graphql} = require('RelayModern');
const userFragment = graphql`  fragment UserFragment on User {    name    friends(after: $cursor, first: $count)      @connection(key: "UserFragment_friends") {      edges {        node {          ...FriendComponent        }      }    }  }`;
  • In the example above, we're querying for the friends field, which is a connection; in other words, it adheres to the connection spec. Specifically, we can query the edges and nodes in the connection; the edges usually contain information about the relationship between the entities, while the nodes are the actual entities at the other end of the relationship; in this case, the nodes are objects of type User representing the user's friends.
  • In order to indicate to Relay that we want to perform pagination over this connection, we need to mark the field with the @connection directive. We must also provide a static unique identifier for this connection, known as the key. We recommend the following naming convention for the connection key: <fragment_name>_<field_name>.
  • We will go into more detail later as to why it is necessary to mark the field as a @connection and give it a unique key in our Updating Connections section.

In order to render this fragment which queries for a connection, we can use the usePaginationFragment Hook:

import type {FriendsListPaginationQuery} from 'FriendsListPaginationQuery.graphql';import type {FriendsListComponent_user$key} from 'FriendsList_user.graphql';
const React = require('React');const {Suspense} = require('React');
const {graphql, usePaginationFragment} = require('react-relay');
type Props = {  user: FriendsListComponent_user$key,};
function FriendsListComponent(props: Props) {  const {data} = usePaginationFragment<FriendsListPaginationQuery, _>(    graphql`      fragment FriendsListComponent_user on User      @refetchable(queryName: "FriendsListPaginationQuery") {        name        friends(first: $count, after: $cursor)        @connection(key: "FriendsList_user_friends") {          edges {            node {              ...FriendComponent            }          }        }      }    `,    props.user,  );

  return (    <>      { != null ? <h1>Friends of {}:</h1> : null}
      <div>        {/* Extract each friend from the resulting data */}        {(data.friends?.edges ?? []).map(edge => {          const node = edge.node;          return (            <Suspense fallback={<Glimmer />}>              <FriendComponent user={node} />            </Suspense>          );        })}      </div>    </>  );}
module.exports = FriendsListComponent;
  • usePaginationFragment behaves the same way as a useFragment (see the Fragments section), so our list of friends is available under data.friends.edges.node, as declared by the fragment. However, it also has a few additions:
    • It expects a fragment that is a connection field annotated with the @connection directive
    • It expects a fragment that is annotated with the @refetchable directive. Note that @refetchable directive can only be added to fragments that are "refetchable", that is, on fragments that are on Viewer, on Query, on any type that implements Node (i.e. a type that has an id field), or on a @fetchable type.
  • It takes two Flow type parameters: the type of the generated query (in our case FriendsListPaginationQuery), and a second type which can always be inferred, so you only need to pass underscore (_).

Is this page useful?