Simple atomic state that can be updated outside of the React life-cycle.

Why use simple-atom?

• Update state outside of a React component.

• No need for React Context, store your atoms in global scope.

• Familiar API, identical usage to React.setState.

• First class Typescript support.

• It's simple, open source and it's tiny! <250 bytes gzipped.

Installation

  npm install simple-atom

Please ensure you have installed react at version v16.8.0 or higher.

Examples

Basic usage

import React from 'react';
// Import 'simple-atom'
import { createAtom, useAtom } from 'simple-atom';

// Create an atom with 'createAtom'
const userAtom = createAtom({ name: 'James', age: 25 });

const MyComponent = () => {
  // Get current value and setter function with 'useAtom' hook
  const [user, setUser] = useAtom(userAtom);

  if (!user) {
    return <h1>You are logged out</h1>;
  }

  return <button onClick={() => setUser(null)}>Logout</button>;
};

Update component state outside of React

// == MyComponent.jsx ==
import React from 'react';
import { createAtom, useAtom } from 'simple-atom';

export const isLoadingAtom = createAtom(false);

const MyComponent = () => {
    const [isLoading] = useAtom(isLoadingAtom);

    if (isLoading) {
        return (
            <div>Loading, please wait...</div>
        );
    }

    return (
        // ...
    );
}

// == other-application-file.js ==
import { isLoadingAtom } from './MyComponent.jsx';

// MyComponent will now re-render with the updated isLoading state
isLoadingAtom.value = true;

Subscribe to state changes

import React from 'react';
import { createAtom, useAtom } from 'simple-atom';

const darkModeAtom = createAtom(() => {
  if (typeof window === 'undefined') {
    return false;
  }
  return window.localStorage.getItem('dark-mode') === 'true';
});

// Add a subscriber that is triggered on atom value change
darkModeAtom.subscribe((value) => {
  window.localStorage.setItem('dark-mode', value.toString());
});

const MyComponent = () => {
  const [darkMode, setDarkMode] = useAtom(darkModeAtom);

  return <button onClick={() => setDarkMode(!darkMode)}>Toggle dark mode</button>;
};

With Typescript

import { createAtom } from 'simple-atom';

type User = { name: string; age: number } | null;

const userAtom = createAtom<User>({ name: 'James', age: 25 });

Acknowledgements

This package was inspired by these projects.

• React
• Jotai
• Zustand

Authors

• James Berry (@jlalmes)

Contributions & PRs are always welcome! 🙌