Skip to main content


Returns a tuple where the first element is the value of state and the second element is a setter function that will update the value of the given state when called.

This hook will subscribe the component to re-render for any changes in the requested state.

Use useRecoilState_TRANSITION_SUPPORT_UNSTABLE() for experimental support for React 18 transitions based on mutating Recoil state.

function useRecoilState<T>(state: RecoilState<T>): [T, SetterOrUpdater<T>];

type SetterOrUpdater<T> = (T | (T => T)) => void;
  • state: an atom or a writeable selector. Writeable selectors are selectors that have both a get and set in their definition while read-only selectors only have a get.

This API is similar to the React useState() hook except it takes a Recoil state instead of a default value as an argument. It returns a tuple of the current value of the state and a setter function. The setter function may either take a new value as an argument or an updater function which receives the previous value as a parameter.

This is the recommended hook to use when a component intends to read and write state.

Using this hook in a React component will subscribe the component to re-render when the state is updated. This hook may throw if the state has an error or is pending asynchronous resolution. Please see this guide.


import {atom, selector, useRecoilState} from 'recoil';

const tempFahrenheit = atom({
key: 'tempFahrenheit',
default: 32,

const tempCelsius = selector({
key: 'tempCelsius',
get: ({get}) => ((get(tempFahrenheit) - 32) * 5) / 9,
set: ({set}, newValue) => set(tempFahrenheit, (newValue * 9) / 5 + 32),

function TempCelsius() {
const [tempF, setTempF] = useRecoilState(tempFahrenheit);
const [tempC, setTempC] = useRecoilState(tempCelsius);

const addTenCelsius = () => setTempC(tempC + 10);
const addTenFahrenheit = () => setTempF(tempF + 10);

return (
Temp (Celsius): {tempC}
<br />
Temp (Fahrenheit): {tempF}
<br />
<button onClick={addTenCelsius}>Add 10 Celsius</button>
<br />
<button onClick={addTenFahrenheit}>Add 10 Fahrenheit</button>