useRemote

Reactive remote data binding powered by Legend-State's sync engine.

Creates an Observable<T> that fetches from and optionally pushes to a remote source. No local persistence — data lives only in memory. Returns decomposed state including loading and error observables.

Demo

useRemote

Loading...

Fetches data from a remote source. No local persistence.

Value

0

Refetch

Usage

Read-only

Hook

import { useRemote } from "@usels/web";

interface User {
  id: number;
  name: string;
}

function Component() {
  const { data$, isLoaded$, error$ } = useRemote<User | null>({
    get: () => fetch("/api/user").then((r) => r.json()),
    initial: null,
  });

  return (
    <div>
      {error$.get() ? (
        <div>Error: {error$.get()?.message}</div>
      ) : isLoaded$.get() ? (
        <div>{data$.get()?.name}</div>
      ) : (
        <div>Loading...</div>
      )}
    </div>
  );
}

Scope

import { createRemote, observable } from "@usels/web";

interface User {
  id: number;
  name: string;
}

function Component() {
  "use scope"
  const { data$, isLoaded$, error$ } = createRemote<User | null>({
    get: () => fetch("/api/user").then((r) => r.json()),
    initial: null,
  });

  return (
    <div>
      {error$.get() ? (
        <div>Error: {error$.get()?.message}</div>
      ) : isLoaded$.get() ? (
        <div>{data$.get()?.name}</div>
      ) : (
        <div>Loading...</div>
      )}
    </div>
  );
}

Read & write

Hook

import { useRemote } from "@usels/web";

function Component() {
  const { data$, refetch } = useRemote<{ count: number }>({
    get: () => fetch("/api/counter").then((r) => r.json()),
    set: ({ value }) =>
      fetch("/api/counter", {
        method: "PUT",
        body: JSON.stringify(value),
      }),
    initial: { count: 0 },
    debounceSet: 500,
  });

  return (
    <div>
      <span>{data$.count.get()}</span>
      <button onClick={() => data$.count.set((c) => c + 1)}>+1</button>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

Scope

import { createRemote, observable } from "@usels/web";

function Component() {
  "use scope"
  const { data$, refetch } = createRemote<{ count: number }>({
    get: () => fetch("/api/counter").then((r) => r.json()),
    set: ({ value }) =>
      fetch("/api/counter", {
        method: "PUT",
        body: JSON.stringify(value),
      }),
    initial: { count: 0 },
    debounceSet: 500,
  });

  return (
    <div>
      <span>{data$.count.get()}</span>
      <button onClick={() => data$.count.set((c) => c + 1)}>+1</button>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

Type

Parameters

Parameter	Type	Description
options	RemoteOptions<T>	- Remote sync configuration.

RemoteOptions

Option	Type	Default	Description
get	() => T | Promise<T>	-	Function that fetches remote data.
set	((params: { value: T; changes: object[]; }) => void | Promise<void>)	-	Function that sends changes to the remote.
initial	T	-	Initial value before the first fetch completes.
mode	"set" | "assign" | "merge" | "append" | "prepend"	"set"	How incoming data merges with existing state.
debounceSet	number	-	Milliseconds to debounce before sending changes to remote.
transform	{ load?: ((value: any) => T) | undefined; save?: ((value: T) => any) | undefined; }	-	Transform data on load/save.

Returns

RemoteReturn<T>

Name	Type	Description
data$	Observable<T>	The synced observable data.
isLoaded$	ReadonlyObservable<boolean>	Whether the initial remote fetch has completed.
isFetching$	ReadonlyObservable<boolean>	Whether a fetch (initial or refetch) is currently in progress.
error$	ReadonlyObservable<Error | undefined>	The most recent sync error, if any.
refetch	() => void	Trigger a manual re-fetch from remote.

Source

View on GitHub