ScopedAtom unstable

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 Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

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/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 unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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"