Skip to main content


A component from the Recoil Sync library to sync atoms using the syncEffect() or urlSyncEffect() atom effects with the browser URL.

This is identical to the <RecoilURLSync> component except that it provides built-in Transit encoding.

function RecoilURLSyncTransit(props: {
handlers?: Array<TransitHandler<any, any>>,
}): React.Node
  • handlers - Optional array of handlers for Custom Classes. It is important that this is a stable or memoized array instance. Otherwise you may miss URL changes as the listener is re-subscribed.

Transit encoding is not as terse or readable as just using JSON, however it can support Map and Set JavaScript containers as well as custom user classes.

Custom Classes

Handlers for custom user classes can be defined with the handlers prop:

type TransitHandler<T, S> = {
tag: string;
class: Class<T>;
write: (T) => S;
read: (S) => T;


class ViewState {
active: boolean;
pos: [number, number];
constructor(active: boolean, pos: [number, number]) { = active;
this.pos = pos;
// ...
const viewStateChecker = custom((x) => (x instanceof ViewState ? x : null));

const HANDLERS = [
tag: 'VS',
class: ViewState,
write: (x) => [, x.pos],
read: ([active, pos]) => new ViewState(active, pos),

function MyApp() {
return (
location={{part: 'queryParams', param: 'state'}}
{/* children */}

const ViewState = atom<ViewState>({
key: 'ViewState',
default: new ViewState(true, [1, 2]),
effects: [syncEffect({storeKey: 'transit-url', refine: viewStateChecker})],