rxelements

Quick Start

bun add rxelements rxjs

import { BehaviorSubject } from "rxjs";
import { element, html } from "rxelements";
const Counter = element(({ subscriptions, onEvent }) => {
 const count = new BehaviorSubject(0);
 subscriptions.add(
 onEvent(".inc", "click").subscribe(() => count.next(count.value + 1)),
 );
 subscriptions.add(
 onEvent(".dec", "click").subscribe(() => count.next(count.value - 1)),
 );
 return html`
 <button class="dec">-</button>
 <span>${count}</span>
 <button class="inc">+</button>
 `;
});
customElements.define("my-counter", Counter);

<my-counter></my-counter>
<script type="module" src="./main.js"></script>

Prerequisites

How It Works

Observable-per-hole rendering

html`
 <div class="sidebar">${nav$}</div>
 <div class="main">${content$}</div>
 <div class="footer">${status$}</div>
`;

Reactive state

mutator call → action Subject → middleware pipeline → reducer (scan) → state$ → selectors → template holes

Routing

URL change → route$ (BehaviorSubject) → switchMap in template → view swap

Component lifecycle

Trade-offs

Progressive Examples

Example 1: Hello World

import { element, html } from "rxelements";
// element() takes a factory function and returns a standard HTMLElement class.
// The factory runs once per mount and returns what to render.
const Hello = element(() => {
 return html`<p>Hello, rxelements.</p>`;
});
// Register as a custom element -- the tag name must contain a hyphen.
customElements.define("hello-world", Hello);

<hello-world></hello-world>

Example 2: Reactive State and Events

import { BehaviorSubject, map } from "rxjs";
import { element, html, when } from "rxelements";
const Toggle = element(({ subscriptions, onEvent }) => {
 // BehaviorSubject holds current state and emits on change.
 const on$ = new BehaviorSubject(false);
 // onEvent(selector, eventName) returns an Observable<Event> using
 // event delegation on the shadow root. The selector targets elements
 // inside the template.
 subscriptions.add(
 onEvent(".toggle-btn", "click").subscribe(() => on$.next(!on$.value)),
 );
 // Derive display text from state -- standard RxJS map.
 const label$ = on$.pipe(map(v => v ? "ON" : "OFF"));
 // when() conditionally renders one branch or the other.
 // Old branch tears down, new branch mounts (switchMap semantics).
 return html`
 <button class="toggle-btn">${label$}</button>
 ${when(
 on$,
 () => html`<p>The light is on.</p>`,
 () => html`<p>The light is off.</p>`,
 )}
 `;
});
customElements.define("light-toggle", Toggle);

Example 3: Lists with repeat()

import { BehaviorSubject, map } from "rxjs";
import { element, html, repeat } from "rxelements";
import { observe as o } from "rxelements";
// observe (aliased as `o` by convention, like lodash's `_`) is a Proxy
// that turns property access on an Observable into a derived Observable.
// o(user$).name is equivalent to user$.pipe(map(u => u.name), distinctUntilChanged()).
const Grocery = element(({ subscriptions, onEvent }) => {
 const items$ = new BehaviorSubject([
 { id: 1, name: "Milk" },
 { id: 2, name: "Bread" },
 ]);
 let nextId = 3;
 // Add a new item on button click.
 subscriptions.add(
 onEvent(".add", "click").subscribe(() => {
 items$.next([...items$.value, { id: nextId++, name: `Item ${nextId - 1}` }]);
 }),
 );
 return html`
 <button class="add">Add item</button>
 <ul>
 ${repeat(
 items$, // Observable<T[]> -- the source list
 (item) => item.id, // keyFn -- stable identity per item
 (item$, index$) => html` <!-- templateFn -- receives per-item Observables -->
 <li>#${index$}: ${o(item$).name}</li>
 `,
 )}
 </ul>
 `;
});
customElements.define("grocery-list", Grocery);

Example 4: Store and Persistence

import { map } from "rxjs";
import {
 element, html, repeat, when,
 createStore, persistMiddleware, loadPersistedState,
 observe as o,
} from "rxelements";
import { BehaviorSubject } from "rxjs";
interface Todo { id: number; text: string; done: boolean; }
interface State { todos: Todo[]; nextId: number; }
// Store definition: reducer handles state transitions,
// mutators are typed action creators, selectors derive values.
const def = {
 reducer: (state: State, action: { type: string; payload?: unknown }) => {
 switch (action.type) {
 case "ADD": return {
 ...state,
 todos: [...state.todos, { id: state.nextId, text: action.payload as string, done: false }],
 nextId: state.nextId + 1,
 };
 case "TOGGLE": return {
 ...state,
 todos: state.todos.map(t => t.id === action.payload ? { ...t, done: !t.done } : t),
 };
 case "REMOVE": return {
 ...state,
 todos: state.todos.filter(t => t.id !== action.payload),
 };
 default: return state;
 }
 },
 mutators: {
 add: (text: string) => ({ type: "ADD" as const, payload: text }),
 toggle: (id: number) => ({ type: "TOGGLE" as const, payload: id }),
 remove: (id: number) => ({ type: "REMOVE" as const, payload: id }),
 },
 selectors: {
 count: (s: State) => s.todos.length,
 doneCount: (s: State) => s.todos.filter(t => t.done).length,
 },
};
// loadPersistedState hydrates from localStorage, falling back to defaults.
// persistMiddleware saves on every state change after the first emission.
const defaults: State = { todos: [], nextId: 1 };
const store = createStore(def, {
 initialState: loadPersistedState("todos", defaults),
 middlewares: [persistMiddleware("todos")],
});
const TodoApp = element(({ subscriptions, onEvent }) => {
 const input = new BehaviorSubject("");
 subscriptions.add(
 onEvent(".add-btn", "click").subscribe(() => {
 if (input.value.trim()) {
 store.mutators.add(input.value.trim()); // Call a mutator to dispatch a typed action.
 input.next("");
 }
 }),
 );
 // Derive the todo list from store state.
 const todos$ = store.state$.pipe(map(s => s.todos));
 return html`
 <input .value=${input} @input=${(e: Event) => input.next((e.target as HTMLInputElement).value)}>
 <button class="add-btn">Add</button>
 <!-- selectors$ are derived Observables with distinctUntilChanged built in. -->
 <p>${store.selectors$.count} items, ${store.selectors$.doneCount} done</p>
 <ul>
 ${repeat(
 todos$,
 (t) => t.id,
 (item$) => html`
 <li>
 <span @click=${() => { item$.subscribe(t => store.mutators.toggle(t.id)).unsubscribe(); }}>
 ${item$.pipe(map(t => t.done ? "✓ " : "○しろまる "))}${o(item$).text}
 </span>
 </li>
 `,
 )}
 </ul>
 `;
});
customElements.define("todo-app", TodoApp);

Example 5: Multi-View App with Routing

import { map, switchMap } from "rxjs";
import {
 element, html, when,
 createRouter, interceptLinks, createStore,
 observe as o,
} from "rxelements";
// createRouter matches URLs against route definitions and emits MatchedRoute objects.
// Routes are matched in definition order -- first match wins.
// "**" is a wildcard catch-all and should always be last.
const router = createRouter({
 routes: [
 { path: "/", component: "home-view" },
 { path: "/about", component: "about-view" },
 { path: "/items/:id", component: "item-view" }, // :id is a path parameter
 { path: "**", component: "not-found" }, // catch-all
 ],
 mode: "history", // "history" (clean URLs) or "hash" (/#/path, no server config needed)
});
const appStore = createStore({
 reducer: (state: { user: string }, action: { type: string; payload?: string }) => {
 if (action.type === "SET_USER") return { ...state, user: action.payload ?? "" };
 return state;
 },
 mutators: {
 setUser: (name: string) => ({ type: "SET_USER" as const, payload: name }),
 },
}, { initialState: { user: "Guest" } });
const App = element(({ subscriptions, unmount$ }) => {
 // switchMap over route$ swaps the view on every navigation.
 // The old view's subscriptions are cleaned up automatically (switchMap semantics).
 const view$ = router.route$.pipe(
 switchMap((route) => {
 switch (route.component) {
 case "home-view": return html`
 <h1>Home</h1>
 <p>Welcome, ${o(appStore.state$).user}</p>
 <a href="/about">About</a> | <a href="/items/42">Item 42</a>
 `;
 case "about-view": return html`<h1>About</h1><a href="/">Back</a>`;
 case "item-view": return html`
 <h1>Item ${route.params.id}</h1>
 <a href="/">Back</a>
 `;
 default: return html`<h1>404</h1><a href="/">Home</a>`;
 }
 }),
 );
 // interceptLinks makes <a> clicks navigate through the router
 // instead of causing full page reloads. It ignores external links,
 // links with target attributes, and modified clicks (ctrl, meta, shift, alt).
 interceptLinks(document.body, router, unmount$);
 return html`<nav></nav><main>${view$}</main>`;
});
customElements.define("multi-app", App);

API Reference

element(factory, options?)

const MyComponent = element(factory, options?);
customElements.define("my-component", MyComponent);

// Return shorthand -- most common. The return value is piped into content$ for you.
const A = element(() => {
 return html`<p>Hello</p>`;
});
// Manual content$ -- useful when you need to push multiple templates over time,
// or when the render trigger comes from outside the factory return.
const B = element(({ content$, subscriptions }) => {
 subscriptions.add(
 interval(1000).pipe(
 map(n => html`<p>Tick ${n}</p>`),
 ).subscribe(content$),
 );
 // No return -- content$ is driven by the subscription above.
});

html tagged template

when(condition,ドル thenFn, elseFn?)

when(
 isEditing$,
 () => html`<input .value=${text$}>`,
 () => html`<span>${text$}</span>`,
);

repeat(items,ドル keyFn, templateFn)

repeat(
 todos$,
 (todo) => todo.id,
 (item$, index$) => html`<li>${item$.pipe(map((t) => t.text))}</li>`,
);

createStore(definition, config)

const store = createStore(
 {
 reducer: (state, action) => { /* ... */ },
 mutators: {
 increment: () => ({ type: "INC" }),
 set: (value: number) => ({ type: "SET", payload: value }),
 },
 selectors: {
 isEven: (state) => state.count % 2 === 0,
 },
 },
 { initialState: { count: 0 } },
);
store.state$ // Observable<State> -- replays current state on subscribe
store.mutators // Bound mutator functions -- call to dispatch
store.selectors$ // { isEven: Observable<boolean> }
store.dispatch(action) // Power-user: raw action dispatch
store.error$ // Observable<StoreError>
store.destroy() // Cleanup

// Logging
const logger = (action$, state$) =>
 action$.pipe(tap((a) => console.log(a.type)));
// Rate limiting
const rateLimited = (action$) =>
 action$.pipe(groupBy((a) => a.type), mergeMap((g) => g.pipe(throttleTime(100))));
createStore(def, { initialState, middlewares: [logger, rateLimited] });

persistMiddleware(key, config?) + loadPersistedState(key, defaults, config?)

const initialState = loadPersistedState("my-app", { count: 0 });
const store = createStore(def, {
 initialState,
 middlewares: [persistMiddleware("my-app")],
});

createRouter(config)

const router = createRouter({
 routes: [
 { path: "/", component: "home-view" },
 { path: "/users/:id", component: "user-view" }, // :id captures a path segment
 { path: "/old-page", redirect: "/new-page" }, // redirect resolves recursively
 { path: "**", component: "not-found" }, // wildcard catch-all (must be last)
 ],
 mode: "history", // or "hash"
 base: "/app", // optional base path for apps hosted under a sub-path
});

router.route$ // Observable<MatchedRoute> -- BehaviorSubject semantics (emits current route immediately)
router.params$ // Observable<Record<string, string>> -- only emits when params actually change
router.query$ // Observable<Record<string, string>> -- only emits when query actually changes
router.navigate("/items/42") // push navigation
router.navigate("/other", { replace: true }) // replace current history entry
router.destroy() // clean up listeners

interceptLinks(root, router, destroy$)

const App = element(({ unmount$ }) => {
 // Intercept all <a> clicks inside document.body.
 // Cleans up automatically when unmount$ emits.
 interceptLinks(document.body, router, unmount$);
 // Works with Shadow DOM roots too:
 // interceptLinks(shadowRoot, router, unmount$);
 return html`
 <a href="/about">About</a> <!-- routed via router.navigate() -->
 <a href="https://example.com">External</a> <!-- ignored (not internal) -->
 <a href="/pdf" target="_blank">PDF</a> <!-- ignored (has target) -->
 `;
});

combineLatest([router.route$, authStore.state$]).pipe(
 tap(([route, auth]) => {
 if (route.path.startsWith("/admin") && !auth.isLoggedIn) {
 router.navigate("/login", { replace: true });
 }
 }),
);

Sanitization

import DOMPurify from "dompurify";
import { element, setDefaultSanitizer } from "rxelements";
// Global default, used by every sanitized() hole:
setDefaultSanitizer((dirty) => DOMPurify.sanitize(dirty));
// Or per element (overrides the default for templates created by this component):
const MyElement = element(factory, {
 sanitizer: (dirty) => DOMPurify.sanitize(dirty),
});

observe(source$) -- property accessor

import { observe as o } from "rxelements";
// Without observe -- manual pipe for every property:
html`<div>${user$.pipe(map(u => u.name), distinctUntilChanged())}</div>`;
// With observe -- property access does the same thing:
html`<div>${o(user$).name}</div>`; // plucks .name reactively
html`<span>${o(user$).address.city}</span>`; // deep nesting works too

fromFetch(url, options?)

fromFetch<User[]>("/api/users", { retry: 3, timeout: 5000 });

htmlSlot tagged template

import { htmlSlot } from "rxelements";
const label$ = new BehaviorSubject("Click me");
const html$ = htmlSlot`<button>${label$}</button>`;
// Emits: "<button>Click me</button>"

elementSlots(tagName, factory, options)

import { elementSlots } from "rxelements";
import { of, interval } from "rxjs";
import { map } from "rxjs/operators";
elementSlots(
 "my-widget",
 ({ slots }) => {
 slots.header = of("Welcome");
 slots.counter = interval(1000).pipe(map(n => `Count: ${n}`));
 },
 {
 templateSelector: "#widget-template",
 expectedSlots: ["header", "counter"],
 },
);

Operators (rxelements/operators)

Pattern Recipes

Data Fetching

1. Debounced Search

import { BehaviorSubject } from "rxjs";
import { debounceTime, distinctUntilChanged, filter, startWith, switchMap } from "rxjs/operators";
import { element, fromFetch, html, repeat } from "rxelements";
const SearchBox = element(({ subscriptions, onEvent }) => {
 const query$ = new BehaviorSubject("");
 const results$ = query$.pipe(
 debounceTime(300),
 filter(q => q.length > 1),
 distinctUntilChanged(),
 switchMap(q => fromFetch<string[]>(`/api/search?q=${encodeURIComponent(q)}`)),
 startWith([] as string[]),
 );
 return html`
 <input @input=${(e: Event) => query$.next((e.target as HTMLInputElement).value)}>
 <ul>${repeat(results$, r => r, (r$) => html`<li>${r$}</li>`)}</ul>
 `;
});

2. Infinite Scroll

import { BehaviorSubject } from "rxjs";
import { auditTime, concatMap, filter, scan, takeUntil, tap } from "rxjs/operators";
import { element, fromFetch, html, repeat } from "rxelements";
import { observe as o } from "rxelements";
const InfiniteList = element(({ subscriptions, onEvent, unmount$ }) => {
 const page$ = new BehaviorSubject(1);
 const items$ = page$.pipe(
 concatMap(p => fromFetch<Item[]>(`/api/items?page=${p}`)),
 scan((all, batch) => [...all, ...batch], [] as Item[]),
 );
 subscriptions.add(
 onEvent(null, "scroll").pipe(
 auditTime(200),
 filter(() => {
 const el = document.documentElement;
 return el.scrollTop + el.clientHeight >= el.scrollHeight - 200;
 }),
 tap(() => page$.next(page$.value + 1)),
 takeUntil(unmount$),
 ).subscribe(),
 );
 return html`
 <ul>${repeat(items$, i => i.id, (i$) => html`<li>${o(i$).name}</li>`)}</ul>
 `;
});

3. WebSocket Stream

import { Observable } from "rxjs";
import { retry, scan } from "rxjs/operators";
import { element, html, repeat } from "rxelements";
function wsObservable(url: string): Observable<string> {
 return new Observable<string>(subscriber => {
 const ws = new WebSocket(url);
 ws.onmessage = (e) => subscriber.next(e.data);
 ws.onerror = (e) => subscriber.error(e);
 ws.onclose = () => subscriber.complete();
 return () => ws.close();
 }).pipe(
 retry({ delay: 3000 }),
 );
}
const Feed = element(() => {
 const messages$ = wsObservable("wss://example.com/feed").pipe(
 scan((all, msg) => [...all.slice(-50), msg], [] as string[]),
 );
 return html`
 <ul>${repeat(messages$, (_, i) => i, (m$) => html`<li>${m$}</li>`)}</ul>
 `;
});

4. Polling with Backoff

import { BehaviorSubject, EMPTY, type Observable, timer } from "rxjs";
import { catchError, switchMap, tap } from "rxjs/operators";
import { fromFetch } from "rxelements";
function pollWithBackoff<T>(url: string, baseInterval = 5000): Observable<T> {
 const errorCount$ = new BehaviorSubject(0);
 return errorCount$.pipe(
 switchMap(errors => {
 const delay = Math.min(baseInterval * 2 ** errors, 60000);
 return timer(0, delay).pipe(
 switchMap(() => fromFetch<T>(url).pipe(
 tap(() => errorCount$.next(0)),
 catchError(() => {
 errorCount$.next(errors + 1);
 return EMPTY;
 }),
 )),
 );
 }),
 );
}
// Usage in a component:
const status$ = pollWithBackoff<Status>("/api/status", 3000);

State Management

5. Optimistic Update Middleware

import { merge, of } from "rxjs";
import { catchError, map, mergeMap } from "rxjs/operators";
import { type Action, fromFetch, type Middleware } from "rxelements";
const optimistic: Middleware<State, Action> = (action$, state$) =>
 action$.pipe(
 mergeMap(action => {
 if (action.type !== "SAVE_ITEM") return of(action);
 // Emit optimistic update immediately
 return merge(
 of({ type: "ITEM_SAVED" as const, payload: action.payload }),
 fromFetch(`/api/items/${action.payload.id}`, {
 method: "PUT",
 body: JSON.stringify(action.payload),
 }).pipe(
 map(() => ({ type: "SAVE_CONFIRMED" as const, payload: action.payload })),
 catchError(() => of({ type: "SAVE_ROLLED_BACK" as const, payload: action.payload })),
 ),
 );
 }),
 );

6. Undo/Redo Middleware

import { Subject, merge } from "rxjs";
import { filter, map, tap, withLatestFrom } from "rxjs/operators";
import { type Action, type Middleware } from "rxelements";
function undoMiddleware<S extends object>(): {
 middleware: Middleware<S, Action>;
 undo: () => void;
 redo: () => void;
} {
 const undoStack: S[] = [];
 const redoStack: S[] = [];
 const undo$ = new Subject<void>();
 const redo$ = new Subject<void>();
 const middleware: Middleware<S, Action> = (action$, state$) =>
 merge(
 action$.pipe(
 withLatestFrom(state$),
 tap(([, state]) => { undoStack.push(state); redoStack.length = 0; }),
 map(([action]) => action),
 ),
 undo$.pipe(
 withLatestFrom(state$),
 filter(() => undoStack.length > 0),
 map(([, current]) => {
 redoStack.push(current);
 return { type: "__RESTORE__", payload: undoStack.pop() } as Action;
 }),
 ),
 redo$.pipe(
 withLatestFrom(state$),
 filter(() => redoStack.length > 0),
 map(([, current]) => {
 undoStack.push(current);
 return { type: "__RESTORE__", payload: redoStack.pop() } as Action;
 }),
 ),
 );
 return {
 middleware,
 undo: () => undo$.next(),
 redo: () => redo$.next(),
 };
}

UI Patterns

7. Form Validation

import { BehaviorSubject, combineLatest } from "rxjs";
import { debounceTime, filter, map, withLatestFrom } from "rxjs/operators";
import { element, html } from "rxelements";
const Form = element(({ subscriptions, onEvent }) => {
 const email$ = new BehaviorSubject("");
 const password$ = new BehaviorSubject("");
 const emailError$ = email$.pipe(
 debounceTime(300),
 map(v => !v ? "Required" : !v.includes("@") ? "Invalid email" : ""),
 );
 const passError$ = password$.pipe(
 debounceTime(300),
 map(v => v.length < 8 ? "Min 8 characters" : ""),
 );
 const valid$ = combineLatest([emailError$, passError$]).pipe(
 map(([e, p]) => !e && !p),
 );
 subscriptions.add(
 onEvent(".submit", "click").pipe(
 withLatestFrom(valid$, email$, password$),
 filter(([, valid]) => valid),
 ).subscribe(([, , email, pass]) => {
 console.log("Submit:", email, pass);
 }),
 );
 return html`
 <input type="email" @input=${(e: Event) => email$.next((e.target as HTMLInputElement).value)}>
 <span style="color:red">${emailError$}</span>
 <input type="password" @input=${(e: Event) => password$.next((e.target as HTMLInputElement).value)}>
 <span style="color:red">${passError$}</span>
 <button class="submit" ?disabled=${valid$.pipe(map(v => !v))}>Submit</button>
 `;
});

8. Drag and Drop

import { BehaviorSubject } from "rxjs";
import { map, switchMap, takeUntil } from "rxjs/operators";
import { element, html } from "rxelements";
const Draggable = element(({ subscriptions, onEvent, unmount$ }) => {
 const pos$ = new BehaviorSubject({ x: 50, y: 50 });
 subscriptions.add(
 onEvent(".handle", "mousedown").pipe(
 switchMap((start: MouseEvent) => {
 const startX = start.clientX - pos$.value.x;
 const startY = start.clientY - pos$.value.y;
 return onEvent(null, "mousemove").pipe(
 map((move: MouseEvent) => ({
 x: move.clientX - startX,
 y: move.clientY - startY,
 })),
 takeUntil(onEvent(null, "mouseup")),
 );
 }),
 takeUntil(unmount$),
 ).subscribe(pos$),
 );
 const style$ = pos$.pipe(
 map(p => `position:absolute;left:${p.x}px;top:${p.y}px;cursor:grab`),
 );
 return html`
 <div class="handle" style=${style$}>Drag me</div>
 `;
});

9. Animated Transitions

import { type Observable } from "rxjs";
import { distinctUntilChanged, switchMap, tap } from "rxjs/operators";
import { type TemplateResult } from "rxelements";
function animatedSwitch(
 condition$: Observable<boolean>,
 thenFn: () => Observable<TemplateResult>,
 elseFn: () => Observable<TemplateResult>,
): Observable<TemplateResult> {
 return condition$.pipe(
 distinctUntilChanged(),
 switchMap(value => {
 const template$ = value ? thenFn() : elseFn();
 return template$.pipe(
 tap(result => {
 // Add enter animation class to all direct children
 for (const child of result.fragment.children) {
 child.classList.add("fade-in");
 }
 }),
 );
 }),
 );
}
// Usage:
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
 .fade-in { animation: fadeIn 0.3s ease-in; }
 @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
`);
const App = element(() => {
 const showA$ = new BehaviorSubject(true);
 return html`
 <button @click=${() => showA$.next(!showA$.value)}>Toggle</button>
 ${animatedSwitch(
 showA$,
 () => html`<div>View A</div>`,
 () => html`<div>View B</div>`,
 )}
 `;
}, { styles: sheet });

Routing

10. Auth Guard Composition

import { combineLatest } from "rxjs";
import { filter } from "rxjs/operators";
import { createRouter, createStore } from "rxelements";
const authStore = createStore({
 reducer: (state: { token: string | null }, action: { type: string; payload?: string }) => {
 if (action.type === "LOGIN") return { token: action.payload ?? null };
 if (action.type === "LOGOUT") return { token: null };
 return state;
 },
 mutators: {
 login: (token: string) => ({ type: "LOGIN" as const, payload: token }),
 logout: () => ({ type: "LOGOUT" as const }),
 },
 selectors: {
 isLoggedIn: (s: { token: string | null }) => s.token !== null,
 },
}, { initialState: { token: null } });
const router = createRouter({
 routes: [
 { path: "/", component: "home-view" },
 { path: "/dashboard", component: "dashboard-view", data: { requiresAuth: true } },
 { path: "/login", component: "login-view" },
 { path: "**", component: "not-found" },
 ],
});
// Guard: runs as a side effect subscription
combineLatest([router.route$, authStore.selectors$.isLoggedIn]).pipe(
 filter(([route, isLoggedIn]) => !!(route.data as any)?.requiresAuth && !isLoggedIn),
).subscribe(([route]) => {
 router.navigate(`/login?redirect=${encodeURIComponent(route.url)}`, { replace: true });
});

Interop

React

import { useEffect, useState } from "react";
// Using an rxelements store in React
function useStore<T extends object>(store: { state$: Observable<T> }): T | null {
 const [state, setState] = useState<T | null>(null);
 useEffect(() => {
 const sub = store.state$.subscribe(setState);
 return () => sub.unsubscribe();
 }, [store]);
 return state;
}
function Dashboard() {
 const state = useStore(appStore);
 if (!state) return null;
 return <div>Count: {state.count}</div>;
}
// Using an rxelements web component in React (wrapper)
function RxElement({ tag, ...props }: { tag: string; [key: string]: unknown }) {
 const ref = React.useRef<HTMLElement>(null);
 useEffect(() => {
 if (ref.current) {
 for (const [key, value] of Object.entries(props)) {
 if (key.startsWith("on")) {
 ref.current.addEventListener(key.slice(2).toLowerCase(), value as EventListener);
 } else {
 ref.current.setAttribute(key, String(value));
 }
 }
 }
 }, [props]);
 return React.createElement(tag, { ref });
}
// <RxElement tag="my-counter" />

Angular

import { Component, OnDestroy, OnInit } from "@angular/core";
import { Subscription } from "rxjs";
// In app.module.ts: add CUSTOM_ELEMENTS_SCHEMA to schemas
// import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
@Component({
 selector: "app-dashboard",
 template: `
 <div>Count: {{ count }}</div>
 <my-counter></my-counter>
 `,
 schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class DashboardComponent implements OnInit, OnDestroy {
 count = 0;
 private sub = new Subscription();
 ngOnInit() {
 // rxelements stores work natively with Angular's async pipe too:
 // count$ = appStore.state$.pipe(map(s => s.count));
 // template: {{ count$ | async }}
 this.sub.add(
 appStore.state$.subscribe(s => { this.count = s.count; }),
 );
 }
 ngOnDestroy() {
 this.sub.unsubscribe();
 }
}

Svelte

<script>
 import { onDestroy } from "svelte";
 // rxelements stores are RxJS Observables -- Svelte auto-subscribes with $
 import { appStore } from "./stores.js";

 // Svelte's $ prefix works with any object that has a .subscribe() method
 $: count = 0;
 const sub = appStore.state$.subscribe(s => { count = s.count; });
 onDestroy(() => sub.unsubscribe());
</script>
<div>Count: {count}</div>
<!-- Web components work natively in Svelte -->
<my-counter></my-counter>

Vue

<template>
 <div>Count: {{ count }}</div>
 <!-- Web components work natively in Vue (configure compilerOptions.isCustomElement) -->
 <my-counter></my-counter>
</template>
<script setup>
import { ref, onMounted, onUnmounted } from "vue";
import { appStore } from "./stores.js";

const count = ref(0);
let sub;

onMounted(() => {
 sub = appStore.state$.subscribe(s => { count.value = s.count; });
});

onUnmounted(() => {
 sub?.unsubscribe();
});
</script>

export default defineConfig({
 plugins: [vue({
 template: {
 compilerOptions: {
 isCustomElement: tag => tag.includes("-"),
 },
 },
 })],
});

Examples

Calculator (apps/calculator/)

Todo List (apps/todo/)

Dashboard (apps/dashboard/)

cd apps/calculator && bun run dev # http://localhost:3001
cd apps/todo && bun run dev # http://localhost:3002
cd apps/dashboard && bun run dev # http://localhost:3003

Testing

Unit tests (no DOM)

test("counter increments", () => {
 const click$ = new Subject();
 const count = new BehaviorSubject(0);
 click$.pipe(scan((n) => n + 1, 0)).subscribe(count);
 click$.next();
 expect(count.value).toBe(1);
});

Store tests

const store = createStore(def, { initialState: { count: 0 } });
store.mutators.increment();
// Assert state$ emissions with firstValueFrom or subscribe:
store.state$.subscribe(state => {
 expect(state.count).toBe(1);
});

Testing with marble diagrams

import { TestScheduler } from "rxjs/testing";
const scheduler = new TestScheduler((actual, expected) => {
 expect(actual).toEqual(expected);
});
scheduler.run(({ cold, expectObservable }) => {
 const source$ = cold("a-b-c|", { a: 1, b: 2, c: 3 });
 const result$ = source$.pipe(prop("value"));
 expectObservable(result$).toBe("a-b-c|", { a: 1, b: 2, c: 3 });
});

E2E tests (Playwright)

cd apps/calculator && bun run test:e2e
cd apps/todo && bun run test:e2e
cd apps/dashboard && bun run test:e2e

When to use rxelements

Packages

Repository Structure

packages/store/ @rxe/store — createStore, persistMiddleware, types (RxJS only)
packages/router/ @rxe/router — createRouter, matchRoute, interceptLinks (RxJS only)
packages/rxe/ rxelements — the framework; depends on @rxe/store + @rxe/router
 src/lib/template/ html, when, repeat, bindings, parseTemplate
 src/lib/element/ element factory, common utilities
 src/lib/observe/ observe() proxy accessor
 src/lib/operators/ untilUnmount, auditRender, withState, prop
 src/lib/fetch/ fromFetch, FetchError
 src/lib/sanitization/ trusted, sanitized
apps/calculator/ Reference app -- calculator
apps/todo/ Reference app -- TodoMVC
apps/dashboard/ Reference app -- real-time monitoring dashboard

FAQ / Troubleshooting

My component renders but never updates

// Will not update:
let count = 0;
html`<span>${count}</span>`;
// Will update:
const count$ = new BehaviorSubject(0);
html`<span>${count$}</span>`;

Memory leak warnings / subscriptions not cleaned up

element(({ subscriptions, onEvent, unmount$ }) => {
 // Preferred: auto-cleanup
 subscriptions.add(
 someStream$.subscribe(handler),
 );
 // Alternative: completion semantics
 someStream$.pipe(takeUntil(unmount$)).subscribe(handler);
});

sanitized() throws "requires a sanitizer function"

import DOMPurify from "dompurify";
import { element, setDefaultSanitizer } from "rxelements";
// Per element:
const MyElement = element(factory, {
 sanitizer: (dirty) => DOMPurify.sanitize(dirty),
});
// Or globally:
setDefaultSanitizer((dirty) => DOMPurify.sanitize(dirty));

Store state$ does not emit after destroy()

onEvent() does not capture events from dynamically added elements

Template holes inside <table>, <select>, or <svg>

// Problematic:
html`<table>${rows$}</table>`;
// Solution: bind inside <tbody>
html`<table><tbody>${rows$}</tbody></table>`;

Component appears blank after moving it in the DOM

How do I pass data between components?

// shared-store.ts
export const appStore = createStore(def, { initialState });
// component-a.ts
import { appStore } from "./shared-store.js";
const A = element(() => html`<div>${o(appStore.state$).count}</div>`);
// component-b.ts
import { appStore } from "./shared-store.js";
const B = element(({ subscriptions, onEvent }) => {
 subscriptions.add(onEvent(".btn", "click").subscribe(() => appStore.mutators.increment()));
 return html`<button class="btn">+</button>`;
});

Can I use rxelements without TypeScript?

License