atom()

Creates a mutable state container that can be read and updated

Overview

The atom() function is the core primitive for storing and updating mutable state in Reatom. Atoms can be called as functions to read their current value or updated using the .set() method.

Import

import { atom } from '@reatom/core'

Signature

function atom<T>(): Atom<T | undefined>
function atom<T>(createState: () => T, name?: string): Atom<T>
function atom<T>(initState: T, name?: string): Atom<T>

Parameters

initState · T | (() => T)

The initial state value, or a function that returns the initial state. If a function is provided, it will be called once during atom initialization.

name · string

Optional name for the atom. Useful for debugging and dev tools. If not provided, an auto-generated name will be used.

Returns

atom · Atom<T>

An atom instance with the following interface:

Show Atom Interface

() · () => T

Call the atom as a function to read its current state.

set · (newState: T) => T

Update the atom’s state to a new value. Returns the new state.

set · (update: (state: T) => T) => T

Update the atom’s state using a function that receives the previous state. Returns the new state.

subscribe · (cb?: (state: T) => any) => Unsubscribe

Subscribe to state changes. The callback is called immediately with the current state, then whenever the state changes. Returns an unsubscribe function.

extend · Extend<this>

Apply extensions to add functionality to the atom. See extend() for details.

Examples

Basic Usage

import { atom } from '@reatom/core'

// Create an atom with an initial value
const counter = atom(0, 'counter')

// Read the current value
const value = counter() // -> 0

// Update with a new value
counter.set(5) // Sets value to 5

// Update with a function
counter.set((prev) => prev + 1) // Sets value to 6

Using a Function for Initial State

// Lazily compute the initial state
const timestamp = atom(() => Date.now(), 'timestamp')

// The function is only called once during initialization
const value = timestamp() // -> 1234567890

Subscribing to Changes

const count = atom(0, 'count')

// Subscribe to changes
const unsubscribe = count.subscribe((state) => {
  console.log('Count changed:', state)
})
// Logs immediately: "Count changed: 0"

count.set(1)
// Logs: "Count changed: 1"

count.set(2)
// Logs: "Count changed: 2"

// Stop listening to changes
unsubscribe()

Atom Without Initial State

// Create an atom that starts as undefined
const maybeValue = atom<string>()

maybeValue() // -> undefined
maybeValue.set('hello')
maybeValue() // -> 'hello'

Complex State

interface User {
  id: string
  name: string
  email: string
}

const user = atom<User>(
  {
    id: '1',
    name: 'Alice',
    email: '[e-mail]'
  },
  'user'
)

// Update using a function
user.set((prev) => ({
  ...prev,
  name: 'Alice Smith'
}))

Type Information

Atom Interface

interface Atom<State = any, Params extends any[] = [newState: State]>
  extends AtomLike<State, []> {
  
  // Update with a new value
  set(...params: Params): State
  
  // Update with a function
  set(update: (state: State) => State): State
}

AtomLike Interface

interface AtomLike<State = any, Params extends any[] = any[], Payload = State> {
  // Call to read state
  (...params: Params): Payload
  
  // Extension system
  extend: Extend<this>
  
  // Subscribe to changes
  subscribe: (cb?: (state: State) => any) => Unsubscribe
  
  // Internal metadata
  __reatom: AtomMeta
}

Related

• computed() - Create derived state that automatically recalculates
• action() - Create logic and side effect containers
• extend() - Add functionality to atoms
• effect() - Create reactive side effects