Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Reactive variables

State containers integrated into Apollo Client's reactivity model


New in 3, reactive variables are a useful mechanism for representing local state outside of the Apollo Client cache. Because they're separate from the cache, reactive can store data of any type and structure, and you can interact with them anywhere in your application without using syntax.

Most importantly, modifying a reactive variable triggers an update of every active query that depends on that variable. Additionally, this updates the React state for components that use the useReactiveVar React hook.

A "depends on" a reactive if any of the query's requested defines a read function that reads the variable's value.

Creating

Create a reactive variable with the makeVar method, like so:

import { makeVar } from '@apollo/client';
const cartItemsVar = makeVar([]);

This code creates a reactive variable with an empty array as its initial value.

Important: The return value of makeVar is a function that you call to read or modify your reactive variable's value.

Reading

To read the value of your reactive variable, call the function returned by makeVar with zero :

const cartItemsVar = makeVar([]);
// Output: []
console.log(cartItemsVar());

Modifying

To modify the value of your reactive variable, call the function returned by makeVar with one (the variable's new value):

const cartItemsVar = makeVar([]);
const cartItemIds = [100, 101, 102];
cartItemsVar(cartItemIds);
// Output: [100, 101, 102]
console.log(cartItemsVar());
// Don't mutate an existing object or array.
// cartItemIds.push(456) will not trigger an update.
// Instead, pass a new copy:
cartItemsVar([...cartItemIds, 456]);
// Output: [100, 101, 102, 456]
console.log(cartItemsVar());

Reacting

As their name suggests, reactive variables can trigger reactive changes in your application. Whenever you modify the value of a reactive variable, queries that depend on that variable refresh, and your application's UI updates accordingly.

With the useReactiveVar hook, React components can also include reactive variable values in their state directly, without wrapping them in a query.

For more information, see Storing local state in reactive variables.

useReactiveVar hook

The useReactiveVar hook can be used to read from a reactive variable in a way that allows the React component to re-render if/when the variable is next updated.

Previously, the only way for a reactive variable to trigger a React component re-render was through the use of useQuery. Now you don't have to be using useQuery to benefit from the reactivity that ReactiveVar<T> provides.

import { makeVar, useReactiveVar } from "@apollo/client";
export const cartItemsVar = makeVar([]);
export function Cart() {
const cartItems = useReactiveVar(cartItemsVar);
// ...

Example application

This example to-do list application uses reactive variables to track both the current list of to-do items and the filter that determines which items to display. See cache.tsx in particular.

Previous
Local-only fields
Next
Client-side schema
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company