ScopedAtom

React helpers for creating Atom instances that belong to one component subtree. make returns a scoped atom with a provider, context, and use accessor. Each provider creates its own Atom once, so different subtrees can use the same scoped atom definition without sharing state.

4 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates a ScopedAtom from a factory function.

When to use

Use to create an atom instance that is owned by a React provider and scoped to a component subtree.

Details

The returned scoped atom includes a Provider, Context, and use accessor. The provider creates the atom once for its lifetime, passing the value prop to the factory when the scoped atom expects input.

Gotchas

use must run under the matching provider. Changing the provider value prop after mount does not recreate the atom.

Signature

declare function make<A extends Atom<any>, Input = never>(f: () => A | (input: Input) => A): ScopedAtom<A, Input>

Example

(Creating a scoped atom with input)

import { make, useAtomValue } from "@effect/atom-react"
import { Atom } from "effect/unstable/reactivity"
import * as React from "react"
import { renderToStaticMarkup } from "react-dom/server"

const User = make((name: string) => Atom.make(name))

function UserName() {
  const atom = User.use()
  const value = useAtomValue(atom)
  return React.createElement("span", null, value)
}

export function App() {
  return React.createElement(
    User.Provider,
    { value: "Ada" },
    React.createElement(UserName)
  )
}

renderToStaticMarkup(React.createElement(App)) // => "<span>Ada</span>"

Models

ScopedAtom interface

Added in v4.0.0 Source

Scoped Atom interface with a provider-backed instance.

Signature

interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
  readonly "~@effect/atom-react/ScopedAtom": "~@effect/atom-react/ScopedAtom";
  Context: Context<A>;
  Provider: [Input] extends [never] ? FC<{
    readonly children?: any;
  }> : FC<{
    readonly children?: any;
    readonly value: Input;
  }>;
  use(): A;
}

Example

(Providing and reading a scoped atom)

import { make, useAtomValue } from "@effect/atom-react"
import { Atom } from "effect/unstable/reactivity"
import * as React from "react"
import { renderToStaticMarkup } from "react-dom/server"

const Counter = make(() => Atom.make(0))

function View() {
  const atom = Counter.use()
  const value = useAtomValue(atom)
  return React.createElement("div", null, value)
}

export function App() {
  return React.createElement(Counter.Provider, null, React.createElement(View))
}

renderToStaticMarkup(React.createElement(App)) // => "<div>0</div>"

Type IDs

TypeId

Added in v4.0.0 Source

Type identifier for ScopedAtom.

Details

Used as the computed property key and marker value stored on ScopedAtom objects.

Signature

declare const TypeId: "~@effect/atom-react/ScopedAtom"

TypeId type

Added in v4.0.0 Source

Literal type used as the ScopedAtom type identifier.

Details

Used as the computed property key and marker value stored on ScopedAtom objects.

Signature

type TypeId = "~@effect/atom-react/ScopedAtom"