A Fragment Container is a higher-order component that allows components to specify their data requirements. A container does not directly fetch data, but instead declares a specification of the data needed for rendering, and then Relay will guarantee that this data is available before rendering occurs.
Table of Contents:
createFragmentContainer has the following signature:
component: The React Component class of the component requiring the fragment data.
fragmentSpec: Specifies the data requirements for the Component via a GraphQL fragment. The required data will be available on the component as props that match the shape of the provided fragment.
fragmentSpecshould be an object whose keys are prop names and values are
graphqltagged fragments. Each key specified in this object will correspond to a prop available to the resulting Component.
relay-compilerenforces fragments to be named as
The Component resulting from
createFragmentContainer will receive the following
environment: The current Relay Environment
To start, let's build the plain React version of a hypothetical
<TodoItem /> component that displays the text and completion status of a
Here's a basic implementation of
<TodoItem /> that ignores styling in order to highlight the functionality:
In Relay, data dependencies are described using GraphQL. For
<TodoItem />, the dependency can be expressed as follows. Note that this exactly matches the shape that the component expected for the
Given the plain React component and a GraphQL fragment, we can now define a Fragment Container to specify this component's data requirements. Let's look at the code first and then see what's happening:
React and Relay support creating arbitrarily complex applications through composition. Larger components can be created by composing smaller components, helping us to create modular, robust applications.
Let's explore how this works via a
<TodoList /> component that composes the
<TodoItem /> we defined above.
View composition is exactly what you're used to — Relay containers are just standard React components. Here's the
<TodoList /> component:
Fragment composition works similarly — a parent container's fragment composes the fragment for each of its children. In this case,
<TodoList /> needs to fetch information about the
Todos that are required by
Note that when composing fragments, the type of the composed fragment must match the field on the parent in which it is embedded. For example, it wouldn't make sense to embed a fragment of type
Story into a parent's field of type
User. Relay and GraphQL will provide helpful error messages if you get this wrong (and if they aren't helpful, let us know!).
When defining a fragment, you can use the
@argumentDefinitions directive to specify any arguments, with potentially default values, that the fragment expects.
For example, let's redefine our
TodoList_list fragment to take some arguments using
Any arguments defined inside
@argumentDefinitions will be local variables available inside the fragment's scope. However, a fragment can also reference global variables that were defined in the root query.
In order to pass arguments to a fragment that has
@argumentDefinitions, you need to use the
TodoList_list example, we would pass arguments to the fragment like so:
As we've learned, Relay fragment containers only declare data requirements as GraphQL fragments. In order to actually fetch and render the specified data, we need to use a
QueryRenderer component to render a root query and any fragment containers included within. Please refer to our
QueryRenderer docs for more details.