Getting Started

Create React App#

Recoil is a state management library for React, so you need to have React installed and running to use Recoil. The easiest and recommended way for bootstrapping a React application is to use Create React App:

npx create-react-app my-app

npx is a package runner tool that comes with npm 5.2+ and higher, see instructions for older npm versions.

For more ways to install Create React App, see the official documentation.

Installation#

The Recoil package lives in npm. To install the latest stable version, run the following command:

npm install recoil

Or if you're using yarn:

yarn add recoil

Or if you're using bower:

bower install --save recoil

RecoilRoot#

Components that use recoil state need RecoilRoot to appear somewhere in the parent tree. A good place to put this is in your root component:

import React from 'react';
import {
  RecoilRoot,
  atom,
  selector,
  useRecoilState,
  useRecoilValue,
} from 'recoil';

function App() {
  return (
    <RecoilRoot>
      <CharacterCounter />
    </RecoilRoot>
  );
}

We'll implement the CharacterCounter component in the following section.

Atom#

An atom represents a piece of state. Atoms can be read from and written to from any component. Components that read the value of an atom are implicitly subscribed to that atom, so any atom updates will result in a re-render of all components subscribed to that atom:

const textState = atom({
  key: 'textState', // unique ID (with respect to other atoms/selectors)
  default: '', // default value (aka initial value)
});

Components that need to read from and write to an atom should use useRecoilState() as shown below:

function CharacterCounter() {
  return (
    <div>
      <TextInput />
      <CharacterCount />
    </div>
  );
}

function TextInput() {
  const [text, setText] = useRecoilState(textState);

  const onChange = (event) => {
    setText(event.target.value);
  };

  return (
    <div>
      <input type="text" value={text} onChange={onChange} />
      <br />
      Echo: {text}
    </div>
  );
}

Selector#

A selector represents a piece of derived state. Derived state is a transformation of state. You can think of derived state as the output of passing state to a pure function that modifies the given state in some way:

const charCountState = selector({
  key: 'charCountState', // unique ID (with respect to other atoms/selectors)
  get: ({get}) => {
    const text = get(textState);

    return text.length;
  },
});

We can use the useRecoilValue() hook to read the value of charCountState:

function CharacterCount() {
  const count = useRecoilValue(charCountState);

  return <>Character Count: {count}</>;
}

Demo#

Below is the finished product:

Echo:

Character Count: 0