Recoil

https://recoiljs.org/docs/
Admin
Recoil is a state management library for React that enables efficient shared state management with a...
Tokens:107,880
Snippets:764
Trust Score:10
Update:7 hours ago
Show doc for...
Tokens:
Raw
### Install Recoil with yarn

Source: https://recoiljs.org/docs/introduction/getting-started/

Alternative installation using yarn.

```shell
yarn add recoil
```

--------------------------------

### Install Recoil with bower

Source: https://recoiljs.org/docs/introduction/getting-started/

Alternative installation using bower.

```shell
bower install --save recoil
```

--------------------------------

### Creating Loadables with RecoilLoadable.of, error, and all

Source: https://recoiljs.org/docs/api-reference/core/Loadable/

Examples of creating Loadables using RecoilLoadable.of, RecoilLoadable.error, and RecoilLoadable.all. The all example maps over the resulting array to sum values.

```jsx
RecoilLoadable.of(123);

RecoilLoadable.error(new Error('ERROR'));

RecoilLoadable.all([
  RecoilLoadable.of(1),
  RecoilLoadable.of(10),
  RecoilLoadable.of(100),
]).map(([a, b, c]) => a+b+c);
```

--------------------------------

### Install nightly build with npm

Source: https://recoiljs.org/docs/introduction/installation/

Installs the nightly build of Recoil from the GitHub repository using npm.

```shell
npm install https://github.com/facebookexperimental/Recoil.git#nightly
```

--------------------------------

### Install nightly build with yarn

Source: https://recoiljs.org/docs/introduction/installation/

Installs the nightly build of Recoil from the GitHub repository using yarn.

```shell
yarn add https://github.com/facebookexperimental/Recoil.git#nightly
```

--------------------------------

### selectorFamily Example

Source: https://recoiljs.org/docs/api-reference/utils/selectorFamily/

Example usage of selectorFamily to create a selector that multiplies a value by a parameter. Demonstrates get and optional set callbacks.

```APIDOC
## selectorFamily Example

### Description
Example usage of selectorFamily to create a selector that multiplies a value by a parameter. Demonstrates get and optional set callbacks.

### Example Code
```jsx
const myNumberState = atom({
  key: 'MyNumber',
  default: 2,
});

const myMultipliedState = selectorFamily({
  key: 'MyMultipliedNumber',
  get: (multiplier) => ({get}) => {
    return get(myNumberState) * multiplier;
  },

  // optional set
  set: (multiplier) => ({set}, newValue) => {
    set(myNumberState, newValue / multiplier);
  },
});

function MyComponent() {
  // defaults to 2
  const number = useRecoilValue(myNumberState);

  // defaults to 200
  const multipliedNumber = useRecoilValue(myMultipliedState(100));

  return <div>...</div>;
}
```
```

--------------------------------

### Install Recoil with npm

Source: https://recoiljs.org/docs/introduction/getting-started/

Installs the latest stable version of Recoil from npm.

```shell
npm install recoil
```

--------------------------------

### LinkToNewView component using useRecoilSnapshot() and snapshot.map()

Source: https://recoiljs.org/docs/api-reference/core/useRecoilSnapshot/

This example defines a LinkToNewView component that uses useRecoilSnapshot() to get the current snapshot, then maps it to a new snapshot with a mutation applied. It renders an anchor with an href generated by a user-defined uriFromSnapshot() function.

```jsx
function LinkToNewView() {
  const snapshot = useRecoilSnapshot();
  const newSnapshot = snapshot.map(({set}) => set(viewState, 'New View'));
  return <a href={uriFromSnapshot(newSnapshot)}>Click Me!</a>;
}
```

--------------------------------

### Example (Asynchronous) - MyDBQuery

Source: https://recoiljs.org/docs/api-reference/core/selector/

An asynchronous selector example that fetches data from a URL and returns the JSON response, demonstrating async selectors with React Suspense.

```APIDOC
## Example (Asynchronous) - MyDBQuery

### Description
An asynchronous selector example that fetches data from a URL and returns the JSON response, demonstrating async selectors with React Suspense.

### Method
selector()

### Parameters
- **key** (string) - Required - Unique identifier for the selector.
- **get** (function) - Required - Async function that computes the selector value. Receives an object with `get` to read other atoms/selectors.

### Request Example
```jsx
const myQuery = selector({
  key: 'MyDBQuery',
  get: async () => {
    const response = await fetch(getMyRequestUrl());
    return response.json();
  },
});
```

### Response
#### Success Response
- **selector** (object) - The created selector object that can be used with Recoil hooks.

#### Response Example
```jsx
const myQuery = selector({
  key: 'MyDBQuery',
  get: async () => {
    const response = await fetch(getMyRequestUrl());
    return response.json();
  },
});
```
```

--------------------------------

### Using RecoilRelayEnvironmentProvider with RecoilRoot

Source: https://recoiljs.org/docs/recoil-relay/api/RecoilRelayEnvironmentProvider/

Example of wrapping an app with RecoilRoot and RecoilRelayEnvironmentProvider, passing an environment and environmentKey.

```jsx
const myEnvironmentKey = new EnvironmentKey('My Environment');

function MyApp() {
  return (
    <RecoilRoot>
      <RecoilRelayEnvironmentProvider
        environment={myEnvironemnt}
        environmentKey={myEnvironmentKey}>
        {/** My App **/}
      </RecoilRelayEnvironmentProvider>
    </RecoilRoot>
  )
}
```

--------------------------------

### Asynchronous selector example with fetch

Source: https://recoiljs.org/docs/api-reference/core/selector/

A complete asynchronous example showing a selector that fetches data and a React component using useRecoilValue with React.Suspense.

```jsx
import {selector, useRecoilValue} from 'recoil';

const myQuery = selector({
  key: 'MyDBQuery',
  get: async () => {
    const response = await fetch(getMyRequestUrl());
    return response.json();
  },
});

function QueryResults() {
  const queryResults = useRecoilValue(myQuery);

  return (
    <div>
      {queryResults.foo}
    </div>
  );
}

function ResultsSection() {
  return (
    <React.Suspense fallback={<div>Loading...</div>}>
      <QueryResults />
    </React.Suspense>
  );
}
```

--------------------------------

### Atom example with useRecoilState

Source: https://recoiljs.org/docs/api-reference/core/atom/

Example of creating an atom with a default value and using useRecoilState to read and update it in a component.

```jsx
import {atom, useRecoilState} from 'recoil';

const counter = atom({
  key: 'myCounter',
  default: 0,
});

function Counter() {
  const [count, setCount] = useRecoilState(counter);
  const incrementByOne = () => setCount(count + 1);

  return (
    <div>
      Count: {count}
      <br />
      <button onClick={incrementByOne}>Increment</button>
    </div>
  );
}
```

--------------------------------

### Async Query Example with selectorFamily

Source: https://recoiljs.org/docs/api-reference/utils/selectorFamily/

Use selectorFamily to create a parameterized async query. The get function receives query parameters and returns a promise. Throws an error if the response contains an error. The component uses useRecoilValue with the family instance.

```jsx
const myDataQuery = selectorFamily({
  key: 'MyDataQuery',
  get: (queryParameters) => async ({get}) => {
    const response = await asyncDataRequest(queryParameters);
    if (response.error) {
      throw response.error;
    }
    return response.data;
  },
});

function MyComponent() {
  const data = useRecoilValue(myDataQuery({userID: 132}));
  return <div>...</div>;
}
```

--------------------------------

### Transaction example using useGotoRecoilSnapshot

Source: https://recoiljs.org/docs/api-reference/core/useGotoRecoilSnapshot/

This example shows how to use useGotoRecoilSnapshot to apply a modified snapshot. It is inefficient because it subscribes the component to all state changes via useRecoilSnapshot.

```jsx
function TransactionButton(): React.Node {
  const snapshot = useRecoilSnapshot(); // Subscribe to all state changes
  const modifiedSnapshot = snapshot.map(({set}) => {
    set(atomA, x => x + 1);
    set(atomB, x => x * 2);
  });
  const gotoSnapshot = useGotoRecoilSnapshot();
  return <button onClick={() => gotoSnapshot(modifiedSnapshot)}>Perform Transaction</button>;
}
```

--------------------------------

### Synchronous selector example with temperature conversion

Source: https://recoiljs.org/docs/api-reference/core/selector/

A complete synchronous example showing a selector that converts between Fahrenheit and Celsius, with a React component using useRecoilState and useResetRecoilState.

```jsx
import {atom, selector, useRecoilState, DefaultValue, useResetRecoilState} 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 instanceof DefaultValue ? newValue : (newValue * 9) / 5 + 32
    ),
});

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

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

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

--------------------------------

### Using graphQLSelector with environmentKey

Source: https://recoiljs.org/docs/recoil-relay/api/RecoilRelayEnvironmentProvider/

Example of defining a GraphQL selector using the environmentKey and using it in a component with useRecoilValue.

```jsx
const myQuery = graphQLSelector({
  key: 'MyQuery',
  environment: myEnvironmentKey,
  query: graphql`...`,
  variables: {},
});

function MyComponent() {
  const results = useRecoilValue(myQuery);
}
```

--------------------------------

### DebugObserver example using useRecoilTransactionObserver_UNSTABLE

Source: https://recoiljs.org/docs/api-reference/core/useRecoilTransactionObserver/

This example defines a DebugObserver component that uses the hook to update window.myDebugState with the contents of atomA and atomB. It is meant to be placed inside a RecoilRoot in the app component.

```jsx
function DebugObserver() {
  useRecoilTransactionObserver_UNSTABLE(({snapshot}) => {
    window.myDebugState = {
      a: snapshot.getLoadable(atomA).contents,
      b: snapshot.getLoadable(atomB).contents,
    };
  });
  return null;
}

function MyApp() {
  return (
    <RecoilRoot>
      <DebugObserver />
      ...
    </RecoilRoot>
  );
}
```

--------------------------------

### Creating an asynchronous Loadable

Source: https://recoiljs.org/docs/api-reference/core/Loadable/

Example of creating a Loadable that asynchronously resolves to 123 using RecoilLoadable.of with a Promise.

```jsx
// Asynchronously resolves to 123
RecoilLoadable.of(Promise.resolve(123));
```

--------------------------------

### Simple Example of graphQLSelector()

Source: https://recoiljs.org/docs/recoil-relay/api/graphQLSelector/

A basic graphQLSelector() that queries an event by ID with fixed variables and maps the response directly.

```jsx
const eventQuery = graphQLSelector({
  key: 'EventQuery',
  environment: myEnvironment,
  query: graphql`
    query MyEventQuery($id: ID!) {
      myevent(id: $id) {
        id
        name
      }
    }
  `,
  variables: {id: 123},
  mapResponse: data => data,
});
```

--------------------------------

### Incremental Loading Example with waitForNone

Source: https://recoiljs.org/docs/api-reference/utils/waitForNone/

Example component that uses waitForNone to render a chart with multiple layers, showing spinners for pending layers and updating as data arrives. Handles errors per layer.

```jsx
function MyChart({layerQueries}: {layerQueries: Array<RecoilValue<Layer>>}) {
  const layerLoadables = useRecoilValue(waitForNone(layerQueries));

  return (
    <Chart>
      {layerLoadables.map((layerLoadable, i) => {
        switch (layerLoadable.state) {
          case 'hasValue':
            return <Layer key={i} data={layerLoadable.contents} />;
          case 'hasError':
            return <LayerErrorBadge key={i} error={layerLoadable.contents} />;
          case 'loading':
            return <LayerWithSpinner key={i} />;
        }
      })}
    </Chart>
  );
}
```

--------------------------------

### useRecoilState example with atom and selector

Source: https://recoiljs.org/docs/api-reference/core/useRecoilState/

Complete example showing how to use useRecoilState with an atom and a writeable selector to manage temperature conversions. The component reads and writes both Fahrenheit and Celsius values, and the selector's set function updates the underlying atom.

```jsx
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 (
    <div>
      Temp (Celsius): {tempC}
      <br />
      Temp (Fahrenheit): {tempF}
      <br />
      <button onClick={addTenCelsius}>Add 10 Celsius</button>
      <br />
      <button onClick={addTenFahrenheit}>Add 10 Fahrenheit</button>
    </div>
  );
}
```

--------------------------------

### Example: using useRecoilValue with atom and selector

Source: https://recoiljs.org/docs/api-reference/core/useRecoilValue/

A complete example demonstrating how to use useRecoilValue to read an atom and a selector. It defines an atom with a default array, a selector that filters out empty strings, and a component that displays both the original and filtered names.

```jsx
import {atom, selector, useRecoilValue} from 'recoil';

const namesState = atom({
  key: 'namesState',
  default: ['', 'Ella', 'Chris', '', 'Paul'],
});

const filteredNamesState = selector({
  key: 'filteredNamesState',
  get: ({get}) => get(namesState).filter((str) => str !== ''),
});

function NameDisplay() {
  const names = useRecoilValue(namesState);
  const filteredNames = useRecoilValue(filteredNamesState);

  return (
    <>
      Original names: {names.join(',')}
      <br />
      Filtered names: {filteredNames.join(',')}
    </>
  );
}
```

--------------------------------

### syncEffect with itemKey and storeKey

Source: https://recoiljs.org/docs/recoil-sync/sync-effect/

Example of using syncEffect with custom itemKey and storeKey to sync an atom with a specific store.

```APIDOC
## syncEffect({ itemKey, storeKey, refine })

### Description
Configures an atom to synchronize with an external store using a custom item key and store key. The itemKey defaults to the atom's key if not specified, and storeKey must match the storeKey of the corresponding <RecoilSync> component.

### Parameters
- **itemKey** (string) - Optional - Unique key to identify the item for the store. Defaults to the atom's key.
- **storeKey** (string) - Optional - Specifies which external store to sync with. Must match the storeKey of the corresponding <RecoilSync>.
- **refine** (function) - Optional - A refinement function for the value.

### Example
```jsx
atom({
  key: 'AtomKey',
  effects: [
    syncEffect({
      itemKey: 'myItem',
      storeKey: 'storeA',
      refine: string(),
    }),
  ],
});
```
```

--------------------------------

### Example using noWait in a selector

Source: https://recoiljs.org/docs/api-reference/utils/noWait/

Example selector that uses noWait to get the loadable state of dbQuerySelector and returns different data based on the loadable state (hasValue, hasError, loading).

```jsx
const myQuery = selector({
  key: 'MyQuery',
  get: ({get}) => {
    const loadable = get(noWait(dbQuerySelector));

    return {
      hasValue: {data: loadable.contents},
      hasError: {error: loadable.contents},
      loading: {data: 'placeholder while loading'},
    }[loadable.state];
  }
})
```

--------------------------------

### useSetRecoilState example with atom and form

Source: https://recoiljs.org/docs/api-reference/core/useSetRecoilState/

Example showing how to use useSetRecoilState to get a setter for an atom and pass it to a child component. The child component updates the state with an updater function when a button is clicked. The Form component renders once, avoiding re-renders on state updates.

```jsx
import {atom, useSetRecoilState} from 'recoil';

const namesState = atom({
  key: 'namesState',
  default: ['Ella', 'Chris', 'Paul'],
});

function FormContent({setNamesState}) {
  const [name, setName] = useState('');
  
  return (
    <>
      <input type="text" value={name} onChange={(e) => setName(e.target.value)} />
      <button onClick={() => setNamesState(names => [...names, name])}>Add Name</button>
    </>
)}

// This component will be rendered once when mounting
function Form() {
  const setNamesState = useSetRecoilState(namesState);
  
  return <FormContent setNamesState={setNamesState} />;
}
```

--------------------------------

### Example URL with query parameter

Source: https://recoiljs.org/docs/recoil-sync/url-persistence/

Shows the resulting URL when the atom is synced with query parameters. The atom key 'CurrentUser' appears as a query parameter.

```text
https://test.com/myapp?CurrentUser=123
```

--------------------------------

### Handle incremental updates with waitForNone

Source: https://recoiljs.org/docs/guides/asynchronous-data-queries/

Use waitForNone to get partial data as it becomes available. The example filters loadables to only those with state 'hasValue' and maps to their contents.

```jsx
const friendsInfoQuery = selector({
  key: 'FriendsInfoQuery',
  get: ({get}) => {
    const {friendList} = get(currentUserInfoQuery);
    const friendLoadables = get(waitForNone(
      friendList.map(friendID => userInfoQuery(friendID))
    ));
    return friendLoadables
      .filter(({state}) => state === 'hasValue')
      .map(({contents}) => contents);
  },
});
```

--------------------------------

### Query with Parameter and Upstream State - graphQLSelectorFamily example

Source: https://recoiljs.org/docs/recoil-relay/api/graphQLSelectorFamily/

Shows how variables and mapResponse can depend on both the family parameter and other upstream Recoil atoms/selectors. The variables callback uses a nested function to access get() and read clientIDAtom. The mapResponse callback also uses get() to read regionForIDSelector(id).

```jsx
const eventQuery = graphQLSelectorFamily({
  key: 'EventQuery',
  environment: myEnvironment,
  query: graphql`
    query MyEventQuery($id: ID!) {
      myevent(id: $id) {
        id
        name
      }
    }
  `,
  variables: id => ({get}) => ({id, clientID: get(clientIDAtom)}),
  mapResponse: (data, {get}) => id => ({
    id,
    name: data.myevent?.name,
    region: get(regionForIDSelector(id)),
  }),
});
```

--------------------------------

### CheckerReturnType<typeof checker>

Source: https://recoiljs.org/docs/refine/api/Utilities/

Extracts the underlying type from a checker function. The example defines a checker for an array of numbers and uses CheckerReturnType to get the type $ReadOnlyArray<number>.

```jsx
const check = array(number());

// $ReadOnlyArray<number>;
type MyArray = CheckerReturnType<typeof check>;
```

--------------------------------

### Create React App with npx

Source: https://recoiljs.org/docs/introduction/getting-started/

Use this command to bootstrap a new React application with Create React App. Requires npm 5.2+ or higher.

```shell
npx create-react-app my-app
```

--------------------------------

### Backward Compatible Example with match() and asType()

Source: https://recoiljs.org/docs/refine/Introduction/

Shows how to upgrade from previous types to a new version using match() and asType(). The checker accepts an object, string, or number and converts them to the expected shape. Demonstrates coercion() returning the result or null.

```jsx
const myChecker: Checker<{str: string}> = match(
  object({str: string()}),
  asType(string(), str => ({str: str})),
  asType(number(), num => ({str: String(num)})),
);

const obj1: {str: string} = coercion(myChecker({str: 'hello'}));
const obj2: {str: string} = coercion(myChecker('hello'));
const obj3: {str: string} = coercion(myChecker(123));
```

--------------------------------

### Using useRecoilValueLoadable in a React component

Source: https://recoiljs.org/docs/api-reference/core/Loadable/

Example of using useRecoilValueLoadable to get a Loadable for a selector and rendering based on its state. The switch statement handles 'hasValue', 'loading', and 'hasError' states.

```jsx
function UserInfo({userID}) {
  const userNameLoadable = useRecoilValueLoadable(userNameQuery(userID));
  switch (userNameLoadable.state) {
    case 'hasValue':
      return <div>{userNameLoadable.contents}</div>;
    case 'loading':
      return <div>Loading...</div>;
    case 'hasError':
      throw userNameLoadable.contents;
  }
}
```

--------------------------------

### Using waitForAll in a selectorFamily with object dependencies

Source: https://recoiljs.org/docs/api-reference/utils/waitForAll/

Example of using waitForAll inside a selectorFamily to fetch multiple related queries (info, invoices, payments) for a given id. The dependencies are provided as an object with named keys.

```jsx
const customerInfoQuery = selectorFamily({
  key: 'CustomerInfoQuery',
  get: id => ({get}) => {
    const {info, invoices, payments} = get(waitForAll({
      info: customerInfoQuery(id),
      invoices: invoicesQuery(id),
      payments: paymentsQuery(id),
    }));

    return {
      name: info.name,
      transactions: [
        ...invoices,
        ...payments,
      ],
    };
  },
});
```

--------------------------------

### Use a request ID as a dependency to refresh a selector query

Source: https://recoiljs.org/docs/guides/asynchronous-data-queries/

Add a request ID as a family parameter or dependency to force re-evaluation. The example uses an atomFamily for the request ID, increments it in a custom hook, and uses it in the selector's get function.

```jsx
const userInfoQueryRequestIDState = atomFamily({
  key: 'UserInfoQueryRequestID',
  default: 0,
});

const userInfoQuery = selectorFamily({
  key: 'UserInfoQuery',
  get: userID => async ({get}) => {
    get(userInfoQueryRequestIDState(userID)); // Add request ID as a dependency
    const response = await myDBQuery({userID});
    if (response.error) {
      throw response.error;
    }
    return response.data;
  },
});

function useRefreshUserInfo(userID) {
  const setUserInfoQueryRequestID = useSetRecoilState(userInfoQueryRequestIDState(userID));
  return () => {
    setUserInfoQueryRequestID(requestID => requestID + 1);
  };
}

function CurrentUserInfo() {
  const currentUserID = useRecoilValue(currentUserIDState);
  const currentUserInfo = useRecoilValue(userInfoQuery(currentUserID));
  const refreshUserInfo = useRefreshUserInfo(currentUserID);

  return (
    <div>
      <h1>{currentUserInfo.name}</h1>
      <button onClick={refreshUserInfo}>Refresh</button>
    </div>
  );
}
```

--------------------------------

### Sync with User Database using RecoilSync

Source: https://recoiljs.org/docs/recoil-sync/implement-store/

Synchronizes with a custom database using read, write, and listen callbacks. The write callback iterates over the diff and sets values, while the listen callback subscribes to updates and returns an unsubscribe function.

```jsx
function SyncWithDB({children}) {
  const connection = useMyDB();
  return (
    <RecoilSync
      storeKey="my-db"
      read={itemKey => connection.get(itemKey)}
      write={({diff}) => {
        for (const [key, value] of diff) {
          connection.set(key, value);
        }
      }}
      listen={({updateItem}) => {
        const subscription = connection.subscribe((key, value) => {
          updateItem(key, value);
        });
        return () => subscription.release();
      }}
    >
      {children}
    </RecoilSync>
  );
}
```

--------------------------------

### Destructuring Example with selectorFamily

Source: https://recoiljs.org/docs/api-reference/utils/selectorFamily/

Use selectorFamily to create a family of selectors for individual fields of an atom. The get function reads a field from the atom, and the set function updates that field while preserving other fields. Components use useRecoilState to read and update individual fields.

```jsx
const formState = atom({
  key: 'formState',
  default: {
    field1: "1",
    field2: "2",
    field3: "3",
  },
});

const formFieldState = selectorFamily({
  key: 'FormField',
  get: field => ({get}) => get(formState)[field],
  set: field => ({set}, newValue) =>
    set(formState, prevState => ({...prevState, [field]: newValue})),
});

const Component1 = () => {
  const [value, onChange] = useRecoilState(formFieldState('field1'));
  return (
    <>
      <input value={value} onChange={onChange} />
      <Component2 />
    </>
  );
}

const Component2 = () => {
  const [value, onChange] = useRecoilState(formFieldState('field2'));
  return (
    <input value={value} onChange={onChange} />
  );
}
```

--------------------------------

### Query with Parameter - graphQLSelectorFamily example

Source: https://recoiljs.org/docs/recoil-relay/api/graphQLSelectorFamily/

Creates a parameterized GraphQL query using graphQLSelectorFamily. The variables callback receives the family parameter (id) and returns the variables object. The mapResponse callback transforms the response data. The component uses useRecoilValue with the family parameter to get the query result.

```jsx
const eventQuery = graphQLSelectorFamily({
  key: 'EventQuery',
  environment: myEnvironment,
  query: graphql`
    query MyEventQuery($id: ID!) {
      myevent(id: $id) {
        id
        name
      }
    }
  `,
  variables: id => ({id}),
  mapResponse: data => data.myevent,
});
```

```jsx
function MyComponent(props) {
  const eventInfo = useRecoilValue(eventQuery(props.eventID));

  return (
    <div>
      <h1>{eventInfo.name}</h1>
    </div>
  );
}
```

--------------------------------

### RecoilRoot example usage

Source: https://recoiljs.org/docs/api-reference/core/RecoilRoot/

Shows how to wrap a component with RecoilRoot to provide Recoil state context. The component must be an ancestor of any component using Recoil hooks.

```jsx
import {RecoilRoot} from 'recoil';

function AppRoot() {
  return (
    <RecoilRoot>
      <ComponentThatUsesRecoil />
    </RecoilRoot>
  );
}
```

--------------------------------

### Register EnvironmentKey for Preloaded Queries

Source: https://recoiljs.org/docs/recoil-relay/graphql-queries/

Creates a preloadedEnvironmentKey and wraps the app with RecoilRelayEnvironment using the preloaded environment. Required before using preloaded queries.

```jsx
export const preloadedEnvironmentKey = new EnvironmentKey('preloaded');

export function AppRoot() {
  const preloadedEnvironment = useRelayEnvironment();
  return (
    <RecoilRoot>
      <RecoilRelayEnvironment
        environmentKey={preloadedEnvironmentKey}
        environment={preloadedEnvironment}>
        {/* My App */}
      </RecoilRelayEnvironment>
    </RecoilRoot>
  )
}
```

--------------------------------

### Using EnvironmentKey with RecoilRelayEnvironment

Source: https://recoiljs.org/docs/recoil-relay/environment/

Creates an EnvironmentKey and uses it with RecoilRelayEnvironment inside RecoilRoot. The environment is obtained at runtime via useMyRelayEnvironment(). Components inside can use Recoil atoms/selectors that reference the key.

```jsx
const myEnvironmentKey = new EnvironmentKey('My Environment');

function MyApp() {
  const myEnvironment = useMyRelayEnvironment();
  return (
    <RecoilRoot>
      <RecoilRelayEnvironment
        environment={myEnvironment}
        environmentKey={myEnvironmentKey}>
        {/* Components here can use Recoil atoms/selectors which reference myEnvironmentKey */}
      </RecoilRelayEnvironment>
    </RecoilRoot>
  )
}
```

--------------------------------

### Another app syncing atom with local storage using RecoilSyncLocalStorage

Source: https://recoiljs.org/docs/recoil-sync/sync-effect/

Example of another app that syncs the same atom with local storage by wrapping the app in RecoilSyncLocalStorage with storeKey 'ui_state'.

```jsx
function AnotherApp() {
  return (
    <RecoilRoot>
      <RecoilSyncLocalStorage storeKey="ui_state">
        ...
      </RecoilSyncLocalStorage>
    </RecoilRoot>
  )
}
```

--------------------------------

### Asynchronous selector with async get

Source: https://recoiljs.org/docs/api-reference/core/selector/

An asynchronous selector that returns a Promise. The get function is async and awaits an async query.

```jsx
const myQuery = selector({
  key: 'MyQuery',
  get: async ({get}) => {
    return await myAsyncQuery(get(queryParamState));
  }
});
```

--------------------------------

### Example (Synchronous) - TempCelsius

Source: https://recoiljs.org/docs/api-reference/core/selector/

A synchronous selector example that converts temperature between Fahrenheit and Celsius, demonstrating writeable selectors with React components.

```APIDOC
## Example (Synchronous) - TempCelsius

### Description
A synchronous selector example that converts temperature between Fahrenheit and Celsius, demonstrating writeable selectors with React components.

### Method
selector()

### Parameters
- **key** (string) - Required - Unique identifier for the selector.
- **get** (function) - Required - Function that computes the selector value. Receives an object with `get` to read other atoms/selectors.
- **set** (function) - Optional - Function that handles setting a new value or resetting. Receives an object with `set` and the incoming value.

### Request Example
```jsx
const tempCelsius = selector({
  key: 'tempCelsius',
  get: ({get}) => ((get(tempFahrenheit) - 32) * 5) / 9,
  set: ({set}, newValue) =>
    set(
      tempFahrenheit,
      newValue instanceof DefaultValue ? newValue : (newValue * 9) / 5 + 32
    ),
});
```

### Response
#### Success Response
- **selector** (object) - The created selector object that can be used with Recoil hooks.

#### Response Example
```jsx
const tempCelsius = selector({
  key: 'tempCelsius',
  get: ({get}) => ((get(tempFahrenheit) - 32) * 5) / 9,
  set: ({set}, newValue) =>
    set(
      tempFahrenheit,
      newValue instanceof DefaultValue ? newValue : (newValue * 9) / 5 + 32
    ),
});
```
```

--------------------------------

### Standalone app syncing atom with URL using RecoilURLSyncTransit

Source: https://recoiljs.org/docs/recoil-sync/sync-effect/

Example of a standalone app that syncs the atom with the URL by wrapping the app in RecoilURLSyncTransit with storeKey 'ui_state' and location part 'hash'.

```jsx
function MyStandaloneApp() {
  return (
    <RecoilRoot>
      <RecoilURLSyncTransit storeKey="ui_state" location={{part: 'hash'}}>
        ...
      </RecoilURLSyncTransit>
    </RecoilRoot>
  );
}
```

--------------------------------

### graphQLSubscriptionEffect usage example

Source: https://recoiljs.org/docs/recoil-relay/api/graphQLSubscriptionEffect/

Example of using graphQLSubscriptionEffect in a Recoil atom's effects array. It subscribes to a GraphQL subscription and updates the atom with the response.

```jsx
const myAtom = atom({
  key: 'MyQuery',
  effects: [
    graphQLSubscriptionEffect({
      environment: myEnvironment,
      query: graphql`
        subscription MyEventSubscription($id: ID!) {
          myevent(id: $id) {
            id
            name
          }
        }
      `,
      variables: {id: 123},
    }),
  ],
});
```

--------------------------------

### Upgrade atom key with read option

Source: https://recoiljs.org/docs/recoil-sync/sync-effect/

Use the read option to specify how to read the atom from the external store when the atom's key has changed. This example reads from 'new_key' first, falling back to 'old_key'.

```jsx
const myAtom = atom<number>({
  key: 'MyAtom',
  default: 0,
  effects: [
    syncEffect({
      itemKey: 'new_key',
      read: ({read}) => read('new_key') ?? read('old_key'),
    }),
  ],
});
```

--------------------------------

### Using RecoilRelayEnvironmentProvider for Relay hooks

Source: https://recoiljs.org/docs/recoil-relay/environment/

Combines RecoilRelayEnvironment and RelayEnvironmentProvider, allowing use of both Recoil and Relay APIs for GraphQL. Requires the environment to be available at runtime.

```jsx
const myEnvironmentKey = new EnvironmentKey('My Environment');

function MyApp() {
  return (
    <RecoilRoot>
      <RecoilRelayEnvironmentProvider
        environment={myEnvironment}
        environmentKey={myEnvironmentKey}>
        {/* Components here can use both Recoil and Relay APIs for GraphQL */}
      </RecoilRelayEnvironmentProvider>
    </RecoilRoot>
  )
}
```

--------------------------------

### DebugObserver component using useRecoilSnapshot()

Source: https://recoiljs.org/docs/api-reference/core/useRecoilSnapshot/

This example shows a DebugObserver component that logs changed atoms using the snapshot. It uses usePrevious to compare snapshots and logs the changed nodes with their loadable values. The component returns null and is intended to be placed inside RecoilRoot.

```jsx
function DebugObserver() {
  const snapshot = useRecoilSnapshot();
  const previousSnapshot = usePrevious(snapshot);
  useEffect(() => {
    console.debug('Changed Atoms:');
    for (const node of snapshot.getNodes_UNSTABLE({isModified: true})) {
      console.debug(node.key, snapshot.getLoadable(node));
    }
  }, [snapshot]);
  return null;
}

function MyApp() {
  return (
    <RecoilRoot>
      <DebugObserver />
      ...
    </RecoilRoot>
  );
}
```

--------------------------------

### useResetRecoilState example with TodoResetButton

Source: https://recoiljs.org/docs/api-reference/core/useResetRecoilState/

Example component that uses useResetRecoilState to reset a todo list state. The returned reset function is used as the onClick handler for a button.

```jsx
import {todoListState} from "../atoms/todoListState";

const TodoResetButton = () => {
  const resetList = useResetRecoilState(todoListState);
  return <button onClick={resetList}>Reset</button>;
};
```

--------------------------------

### Example usage of useRecoilStateLoadable

Source: https://recoiljs.org/docs/api-reference/core/useRecoilStateLoadable/

Example component using useRecoilStateLoadable to read an asynchronous selector. It switches on the loadable state to render the value, a loading message, or throw an error.

```jsx
function UserInfo({userID}) {
  const [userNameLoadable, setUserName] = useRecoilStateLoadable(userNameQuery(userID));
  switch (userNameLoadable.state) {
    case 'hasValue':
      return <div>{userNameLoadable.contents}</div>;
    case 'loading':
      return <div>Loading...</div>;
    case 'hasError':
      throw userNameLoadable.contents;
  }
}
```

--------------------------------

### set() checker example

Source: https://recoiljs.org/docs/refine/api/Collection_Checkers/

Validates that a value is a Set with all elements passing the given checker. The example uses number() and tests a Set of numbers, asserting success and failure cases.

```jsx
// define checker
const check = set(number());

// test a value
const result = check(new Set([1, 2]));
assert(result.type === 'success');

// result should typecheck
const value: $ReadOnlySet<number> = result.value;

// test an invalid value
assert(check('test').type === 'failure');
assert(check({a: 'test', b: 'other', c: 3}).type === 'failure');
```

--------------------------------

### Custom class handler example with RecoilURLSyncTransit

Source: https://recoiljs.org/docs/recoil-sync/api/RecoilURLSyncTransit/

Shows how to define a custom class ViewState, a checker using custom(), and a HANDLERS array with tag 'VS'. The MyApp component wraps RecoilURLSyncTransit with the handlers, and the ViewState atom uses syncEffect with the same storeKey and refine.

```tsx
class ViewState {
  active: boolean;
  pos: [number, number];
  constructor(active: boolean, pos: [number, number]) {
    this.active = active;
    this.pos = pos;
  }
  // ...
}
const viewStateChecker = custom((x) => (x instanceof ViewState ? x : null));

const HANDLERS = [
  {
    tag: 'VS',
    class: ViewState,
    write: (x) => [x.active, x.pos],
    read: ([active, pos]) => new ViewState(active, pos),
  },
];

function MyApp() {
  return (
    <RecoilRoot>
      <RecoilURLSyncTransit
        storeKey="transit-url"
        location={{part: 'queryParams', param: 'state'}}
        handlers={HANDLERS}>
        {/* children */}
      </RecoilURLSyncTransit>
    </RecoilRoot>
  );
}

const ViewState = atom<ViewState>({
  key: 'ViewState',
  default: new ViewState(true, [1, 2]),
  effects: [syncEffect({storeKey: 'transit-url', refine: viewStateChecker})],
});
```
Tokens:
Raw