Riposte

State with Atoms

2026-05-31T15:40:05.566249418Z

useState is enough for state owned by one component. When state needs to be shared across components that aren’t in a simple parent-child line — and you’d rather not thread props through every layer between them — reach for riposte-atoms: a Jotai-inspired model of small, independent, identity-based units of state.

Add the dependency (it pulls in the core transitively):

libraryDependencies += "io.github.edadma" %%% "riposte-atoms" % "0.0.2"

import io.github.edadma.riposte.atoms.*

Atoms

An atom is a handle to a unit of state — a key, not a container. The value lives in a Store; the atom just identifies it. A primitive atom is seeded with a value:

val countAtom = atom(0)   // WritableAtom[Int]

A derived atom computes its value from the atoms it reads, and recomputes automatically whenever any of those change. The get it receives both reads a dependency and records it:

val doubledAtom = atom(get => get(countAtom) * 2)        // read-only
val sumAtom     = atom(get => get(aAtom) + get(bAtom))   // tracks both

Because dependencies are recorded per evaluation, an atom that reads different atoms on different runs is tracked correctly each time.

Using atoms in components

Three hooks connect atoms to components, mirroring useState:

useAtom(a) → (value, set) — read and write.
useAtomValue(a) → value — read only.
useSetAtom(a) → set — write only (doesn’t subscribe, so the component doesn’t re-render when the atom changes).

val Counter = view {
  val (count, setCount) = useAtom(countAtom)
  val doubled           = useAtomValue(doubledAtom)

  div(
    p(s"count: $count, doubled: $doubled"),
    button(onClick := (_ => setCount(count + 1)), "Increment"),
  )
}

Reading an atom subscribes the component to just that atom: it re-renders when that atom’s value changes and not otherwise. So Counter above re-renders when countAtom changes; doubledAtom recomputes and its readers re-render too; a component that reads neither is untouched. This fine-grained subscription is automatic — no selectors required for the common case.

Stores and scoping

Every atom hook resolves its store from the nearest StoreProvider ancestor, falling back to the process-wide Store.default. For most apps the default is all you need, and the examples above work with no setup.

To give a subtree its own isolated state — for tests, for resetting a region, or for rendering the same UI against different data — create a store with new Store and wrap the subtree in a StoreProvider. The same atoms then hold independent values under each provider:

val App = view {
  StoreProvider(new Store) {
    Counter()
  }
}

More atom kinds

Beyond primitive and read-only derived atoms, the module provides:

Writable-derived atoms — a derived value that also knows how to be written, by fanning the write out to the atoms that back it:

val celsiusAtom = atom(0.0)
val fahrenheitAtom = atom(
  read  = get => get(celsiusAtom) * 9 / 5 + 32,
  write = (get, set, f: Double) => set(celsiusAtom, (f - 32) * 5 / 9),
)

Action atoms — a write-only “command” that carries no readable value but mutates several atoms at once when dispatched:

val resetAll = action((get, set, _: Unit) => {
  set(countAtom, 0)
  set(celsiusAtom, 0.0)
})
// useSetAtom(resetAll) gives you a dispatcher

selectAtom(a, f) — derive a narrowed slice of a larger atom that only notifies when that slice changes, so readers don’t re-render on unrelated parts of the source.

atomFamily(make) — a function from a parameter to an atom, memoized so the same parameter always yields the same atom. Use it for per-id state (one atom per row, per user, …).

atomWithStorage(key, default) — a primitive atom that persists to localStorage under key and re-hydrates on load. A typed overload takes encode/decode for non-string values.

atomLoadable(future) — wraps an async computation as an atom whose value is a Loadable with loading / data / error states, so a component can render each phase without manual effect plumbing.

Next: Routing.

Component library (salle)

2026-05-31T15:40:05.566249418Z

salle is a component library for Riposte — the styled, ready-made widgets layer that sits on top of the core’s elements and hooks. (The name is the fencing salle: the hall where the bouts happen.) It’s a separate published artifact that depends only on riposte‘s public API, so it adds no weight to an app that doesn’t use it.

libraryDependencies += "io.github.edadma" %%% "riposte-salle" % "0.0.2"

import io.github.edadma.riposte.*
import io.github.edadma.riposte.salle.*

val Form = view {
  div(
    Input(placeholder = "Email", inputType = "email"),
    Checkbox(label = "Remember me", defaultChecked = true),
    Button("Sign in", color = Color.Primary, onClick = () => submit()),
  )
}

Every salle component is an ordinary function with default arguments, returning a VNode — so you call it like any other component and override only the props you care about.

The skin system

The idea that organizes salle: components describe intent, not appearance. A button doesn’t know it’s blue or rounded — it knows it’s a Color.Primary, Size.Md, ButtonVariant.Solid. A Skin translates that intent into the CSS classes of one concrete styling system, and the active skin is read from context. So you can re-skin an entire app’s look from a single provider at the root, with no change at any call site.

Two skins ship:

SalleSkin (the default) — salle’s own look. It emits salle-* classes whose rules live in salle.css. An app that configures nothing still gets a styled UI.
DaisySkin — emits the DaisyUI class vocabulary (btn btn-primary btn-sm). The styles come from DaisyUI + Tailwind in your own CSS build; salle just produces the class names.

Choose one with SkinProvider near the root; everything below it picks it up through useSkin:

import io.github.edadma.riposte.salle.*

render(
  SkinProvider(DaisySkin) {
    App()
  },
  dom.document.getElementById("app"),
)

Writing your own skin is implementing the Skin trait — one method per component, mapping its semantic props to your classes.

Light & dark theming

Skins decide which design system renders a component; themes decide its light/dark palette. They’re orthogonal: a single global theme name drives a data-theme attribute on the document root, and both skins respond to it — SalleSkin through the [data-theme="…"] token blocks in salle.css, DaisySkin through DaisyUI’s own themes.

The theme set is open. salle ships light and dark; system follows the OS preference; and any other name selects whatever [data-theme="…"] block your app defines ("dracula", a brand theme, …).

useTheme() is the hook. It returns a named tuple and, on first read, installs salle’s theme management — setting data-theme, persisting the choice to localStorage, following the OS while on "system", and syncing across tabs:

val t = useTheme()
//  t.theme    : String        — the stored name ("system" / "light" / "dark" / custom)
//  t.resolved : String        — the concrete theme ("system" resolved to the OS pref)
//  t.setTheme : String => Unit — select any theme name
//  t.toggle   : () => Unit     — flip light ⇄ dark

For the common cases salle ships two ready components:

ThemeToggle                              // an icon button (sun/moon): light ⇄ dark
ThemeSelect(Seq("system", "light", "dark"))   // a <select> bound to the active theme

Both follow the active skin, and ThemeSelect is the way to surface a larger open theme set. To define your own theme, add a [data-theme="name"] block (overriding the --salle-* custom properties) and offer its name through setTheme/ThemeSelect — see Theming the default look.

The style vocabulary

Two enums are shared by every component that has them, so the same values mean the same thing everywhere:

Color — Default, Primary, Secondary, Accent, Neutral, Info, Success, Warning, Error (mirrors DaisyUI’s palette). Default applies no color modifier — the component keeps its base look.
Size — Xs, Sm, Md, Lg, Xl.

A component’s variant axis is specific to it, so each declares its own enum — e.g. ButtonVariant (Solid, Outline, Dash, Soft, Ghost, Link).

Components

Button

Button("Save")                                             // default
Button("Delete", color = Color.Error)
Button("Cancel", color = Color.Primary, variant = ButtonVariant.Outline)
Button("Go", size = Size.Sm, onClick = () => navigate("/next"))
Button("Disabled", disabled = true)

The three style axes — color, variant, size — are independent. The disabled state is reflected both as the HTML attribute and as data-state, for styling hooks.

Input

A single-line text field that’s controlled when you pass value = Some(...) (your app owns the text and is notified through onChange) or uncontrolled when you don’t (salle holds it internally, seeded from defaultValue):

// Controlled — the app drives the value:
val (email, setEmail, _) = useState("")
Input(value = Some(email), onChange = setEmail, inputType = "email")

// Uncontrolled — salle holds the text:
Input(defaultValue = "draft", placeholder = "Notes")

// Validation state:
Input(invalid = true, color = Color.Error)

invalid switches to the error treatment and sets aria-invalid.

Checkbox and Toggle

Both share the Input’s controlled/uncontrolled model (checked: Option[Boolean] + defaultChecked), and both render a <label> around the box when given a non-empty label so clicking the text toggles it. Toggle is the same control styled as a switch, with role="switch" and aria-checked for assistive tech:

Checkbox(label = "Accept terms", onChange = setAccepted)
Checkbox(label = "Subscribed", defaultChecked = true)

Toggle(label = "Wi-Fi", defaultChecked = true)
Toggle(label = "Dark mode", checked = Some(dark), onChange = setDark)

Select

A single-select dropdown — built as a custom ARIA combobox (not a native <select>), so it supports typeahead, keyboard navigation, a clear affordance, and skin-styled options. Options are built with Opt; the chosen value follows the same controlled/uncontrolled model as the form controls above:

Select(
  options = Seq(
    Opt("us", "United States"),
    Opt("ca", "Canada"),
    Opt("mx", "Mexico", disabled = true),
  ),
  placeholder = "Country",
  clearable = true,
  onChange = setCountry,
)

Opt(value, label, disabled) defaults label to value. Select takes the usual color/size/disabled/invalid, plus clearable (adds a reset button) and name (emits a hidden input so it participates in native form submission). It’s fully keyboard-driven (arrows, Home/End, Enter/Space, Escape, type-to-search) and mirrors its state to data-* (data-state, data-value, and per-option data-selected/data-active).

ImageCard

A single image tile for a media grid. The full image loads lazily — only once the tile nears the viewport (built on useIntersectionObserver) — showing a skeleton until it arrives and fading in on load. If src fails it tries fallback, then shows an error placeholder:

ImageCard(
  src = thumbUrl,
  alt = "Sunset over the bay",
  ratio = "16/9",                 // reserves space so the grid doesn't reflow
  fit = ImageFit.Cover,           // Cover | Contain | Fill | ScaleDown
  badge = Some(span("4K")),       // a corner tag
  overlay = Some(downloadButton), // hover content
  onClick = () => open(fullUrl),
)

ratio is a CSS aspect-ratio ("16/9", "1/1"); fit controls cropping; rounded (default true) rounds the corners; lazyLoad = false opts out of deferred loading. State is mirrored to data-state (loading/loaded/error) and data-inview.

Layout

Two layout systems sit alongside the components — one for precise column layouts, one for packed ones.

Grid (Row / Col)

A 24-column grid in the Ant Design tradition: a Row lays out equal column tracks, and each Col spans some of them, with per-breakpoint spans, offsets, and ordering. Reach for it when you want columns to line up on a stated grid:

Row(gutterX = 24)(
  Col(span = 16)(main),
  Col(span = 8)(sidebar),
)

// Responsive: full width on phones, half on small, a third from medium up.
Row()(
  Col(xs = 24, sm = 12, md = 8)(card1),
  Col(xs = 24, sm = 12, md = 8)(card2),
  Col(xs = 24, sm = 12, md = 8)(card3),
)

Row(cols, gutterX, gutterY, justify, align) — cols defaults to 24; gutterX/gutterY are the pixel gutters; justify aligns columns along the row (start/end/center/between/around/evenly) and align across it (start/end/center/stretch/baseline). Col(span, offset, order, xs…xxl) — span is the base width (full row by default), offset pushes it right, order overrides visual position, and xs/sm/md/lg/xl/xxl set per-breakpoint spans (each inheriting the next smaller when unset). Both take their children curried: Row(…)(cols*), Col(…)(content*).

Masonry

A Pinterest-style packed layout: tiles of differing heights flow into a fixed number of equal-width columns, each tile placed into the currently shortest column (balanced columns, left-to-right reading order — unlike a CSS multi-column flow). It measures real tile heights (via useResizeObserver) and re-packs on resize or when children change:

Masonry(columns = 3, gap = 16)(tiles*)

// Column count follows the viewport:
Masonry(columns = MasonryColumns.Responsive(base = 1, md = 2, lg = 3))(tiles*)
// or the shorthand:
MasonryResponsive(base = 1, sm = 2, lg = 3)(tiles*)

A bare Int for columns is a fixed count (Masonry(columns = 3)); MasonryColumns.Responsive picks a count by viewport against the standard breakpoints. Tiles should size naturally — an ImageCard with a ratio is the canonical cell. The pure packing function, layoutMasonry(heights, columns, gap, containerWidth), is exposed too if you need the geometry without the component.

useControllable

The hook every salle form control is built on, and one you can reuse for your own controlled/uncontrolled components. Given the optional controlled value, a default, and an onChange, it returns a (current, set) pair that does the right thing in either mode:

val (current, set) = useControllable(value, default, onChange)

In controlled mode (value is Some) set only calls onChange — the next render’s Some carries the new value back. In uncontrolled mode (value is None) set updates internal state and calls onChange as a notification. Writing a component against this pair means its body is identical in both modes.

Theming the default look

SalleSkin‘s styles live in salle.css. Include it once in your app, then put any overrides after it. Every rule sits in a low-priority @layer salle cascade layer, so your own unlayered CSS always wins — no !important, no specificity fights. Two ways to retheme, both plain CSS:

Values — override the --salle-* custom properties (colors, radius, focus ring) at :root or under a [data-theme=…] block.
Rules — restyle a selector directly (say, add a shadow to .salle-btn).

:root {
  --salle-radius: 0.25rem;
  --salle-color-primary: #0c8599;
}

/* A custom theme, selectable by name through setTheme / ThemeSelect. */
[data-theme="ocean"] {
  color-scheme: dark;
  --salle-color-primary: #0c8599;
}

salle’s own light and dark palettes are exactly such blocks, so the theming hook and components above pick up a custom one with no extra wiring.

Classes follow a BEM-ish convention: a base (.salle-btn) plus independent modifiers for color (--primary), variant (--outline), and size (--sm). Each color modifier sets a single custom property that the variant rules reinterpret, so color × variant combine without a rule per pair.

Routing

2026-05-31T15:40:05.566249418Z

riposte-router maps URLs to views for single-page apps. It’s built entirely on the core’s public API — useSyncExternalStore for the location, context for route params and the outlet, the DSL for links — so it touches no internals and adds nothing you couldn’t build yourself; it just saves you from doing so.

Add the dependency (it pulls in the core transitively):

libraryDependencies += "io.github.edadma" %%% "riposte-router" % "0.0.2"

import io.github.edadma.riposte.*
import io.github.edadma.riposte.router.*

A router and some routes

Router establishes the routing context and tracks the current location. Inside it, Routes picks the best-matching route for the current URL and renders it. route pairs a path pattern with a view:

val App = view {
  Router() {
    Routes(
      route("/")(Home()),
      route("/about")(About()),
      route("/users/:id")(UserPage()),
      route("*")(NotFound()),
    )
  }
}

Routes picks the most specific match regardless of declaration order, so a static /users/new wins over the dynamic /users/:id even if :id is declared first. A "*" pattern is a catch-all — the idiomatic not-found route.

History vs. hash mode

Router defaults to History mode — clean URLs (/users/7) via the History API, which needs the server to fall back to index.html for unknown paths. For static hosting with no such fallback, use hash mode, which keeps everything after a # (/#/users/7):

Router(RouterMode.Hash) {
  Routes(…)
}

Params

A :name segment captures a path parameter. Read the matched params with useParams, which returns a Params (a Map[String, String]):

val UserPage = view {
  val id = useParams().getOrElse("id", "")
  p(s"User $id")
}

useParams reads the params of the nearest enclosing route, and params accumulate down a nested branch — a child route sees its own captures plus all of its ancestors’.

Alternatively, take the params directly in the route declaration:

route("/users/:id")(params => UserDetail(params("id")))

Link renders an <a> that navigates in-app — no full-page reload:

nav(
  Link("/", "Home"),
  Link("/about", "About"),
)

NavLink is a Link that adds an active CSS class when its target matches the current location. It’s curried — options first, then the children — and end = true requires an exact path match (otherwise a prefix match counts, so /users is active on /users/7 too):

nav(
  NavLink("/", activeClass = "current", end = true)("Home"),
  NavLink("/users", activeClass = "current")("Users"),
)

To navigate imperatively — after a form submit, say — call navigate. Pass replace = true to replace the current history entry instead of pushing a new one:

button(onClick := (_ => navigate("/users/42")), "Open user 42")
navigate("/login", replace = true)

Nested routes

A route can take child routes. The parent matches a prefix of the path and renders its matched child wherever its view places an Outlet; the child’s pattern is relative to the parent. index(...) declares the child shown when the parent’s own path is matched exactly:

Routes(
  route("/dashboard")(Dashboard())(
    index(Overview()),
    route("settings")(Settings()),
    route("users/:id")(UserDetail()),
  ),
)

val Dashboard = view {
  div(
    h1("Dashboard"),
    nav(
      NavLink("/dashboard/settings", end = true)("Settings"),
    ),
    Outlet,   // Overview, Settings, or UserDetail renders here
  )
}

This is how you build shared layouts: the parent route is the chrome (header, sidebar, nav), and Outlet is the hole the active child fills.

Query strings

useSearchParams reads and updates the query portion of the URL, in both History and hash modes. It returns the current params and a setter; the setter takes the new params and a replace flag:

val Search = view {
  val (params, setParams) = useSearchParams()
  val q = params.getOrElse("q", "")

  input(
    value := q,
    onInput := (e => setParams(Map("q" -> targetValue(e)), true)),
  )
}

Per-route error boundaries

route(...).catchErrors(fallback) wraps a route’s view in an error boundary: if rendering that route — or any descendant up to a nested route’s own boundary — throws, fallback(error) shows in its place instead of the failure tearing down the app. The route keeps matching, so fixing the cause and re-rendering recovers:

route("/report/:id")(Report())
  .catchErrors(err => div(cls := "error", s"Couldn't load report: ${err.getMessage}"))

Lazy routes

lazyView defers loading a view until it’s first rendered, backing onto JavaScript’s dynamic import() so the bundler can split that view into its own chunk. It takes a function returning a js.Promise[VNode] and an optional fallback shown while loading:

route("/admin")(
  lazyView(() => loadAdminPanel(), fallback = p("Loading…"))
)

Pair it with code-splitting in your build to keep the initial bundle small and load heavy routes on demand.

Scroll restoration

ScrollRestoration is a component that resets (and, for back/forward navigation, restores) the scroll position as the location changes — the behavior browsers do for free on full page loads but not for in-app navigation. Render it once, inside the Router:

val App = view {
  Router() {
    ScrollRestoration()
    Routes(…)
  }
}

Quick Start

2026-05-31T15:40:05.566249418Z

This walks through a complete, tiny Riposte application: a counter you can click.

Describe the UI

A component is a value built with view { … }. Inside the block you call hooks like useState at the top level — view runs the body with a Hooks context in scope — and return a VNode built with the DSL’s HTML tags, attributes, and event handlers:

import io.github.edadma.riposte.*

val Counter = view {
  val (count, set, update) = useState(0)

  div(
    p(s"Count: $count"),
    button(onClick := (_ => update(_ + 1)), "Increment"),
    button(onClick := (_ => set(0)), "Reset"),
  )
}

useState returns three things: the current state, a set function that replaces it, and an update function that derives the next value from the previous one. Reach for update whenever the new value depends on the old.

Mount it

Rendering attaches a component to a DOM node and keeps it in sync as state changes:

import org.scalajs.dom

@main def main(): Unit =
  val root = dom.document.getElementById("app")
  render(Counter(), root)

Note the Counter() — a view is a no-props component, so you call it with empty parens to produce a node, whether you’re handing it to render or nesting it as a child of another element.

<!-- index.html -->
<div id="app"></div>
<script src="main.js"><</script>

Build the JavaScript with fastLinkJS (development) or fullLinkJS (production):

sbt app/fastLinkJS

That is the whole loop: clicking a button calls a setter, the setter schedules a re-render, the reconciler diffs the new tree against the old, and only the changed text node is touched.

Where to go next

Components & the DSL — tags, attributes, children, events.
Hooks — state, effects, refs, and the rules that govern them.
State with atoms — share state across components without prop-drilling.
Routing — map URLs to views in a single-page app.

Modules & API

2026-05-31T15:40:05.566249418Z

Riposte ships as four independently published artifacts under the io.github.edadma organization, all at the same version. The three sibling artifacts depend on the core transitively, so adding any of them is enough — you don’t list riposte separately.

Artifact	Import	What it gives you
`riposte`	`io.github.edadma.riposte.*`	Components, hooks, the DSL, rendering
`riposte-atoms`	`io.github.edadma.riposte.atoms.*`	Shared atomic state
`riposte-router`	`io.github.edadma.riposte.router.*`	Client-side routing
`riposte-salle`	`io.github.edadma.riposte.salle.*`	Styled, skinnable component library

riposte-salle also depends on riposte transitively. The current published version is 0.0.2.

riposte (core)

The React-inspired core: an immutable VNode tree, a reconciler that diffs it against the live DOM, function components, and hooks.

Components

API	Purpose
`view { … }`	A no-props component. Call it `C()`.
`component[P] { p => … }`	A component taking one prop (or a named tuple).
`component[A, B] { (a, b) => … }`	Positional props (up to four).
`container { children => … }`	A component that wraps children (a slot).
`container[P] { (p, children) => … }`	Props + children; called curried `C(p)(kids…)`.
`memo(c)`	Bail out of re-render when props are unchanged.

See Components & the DSL.

Hooks

Hook	Returns / does
`useState(initial)`	`(value, set, update)`
`useReducer(reducer, initial)`	`(state, dispatch)`
`useEffect(body, deps)`	Run a side effect after paint; `body` returns cleanup
`useLayoutEffect(body, deps)`	Same, but synchronously before paint
`useRef(initial)`	A mutable `.current` box; bind to a node with `ref`
`useMemo(compute, deps)`	Cache an expensive value
`useCallback(fn, deps)`	Cache a function’s identity
`useId()`	A stable unique id string
`useContext(ctx)`	The nearest provided context value
`useTransition(target, durationMs)`	An eased `Double` animated each frame
`useSyncExternalStore(sub, snapshot)`	Subscribe to an external store
`useImperativeHandle(ref, factory, deps)`	Expose an imperative handle to a parent’s `ref`
`useDeferredValue(value)`	A copy of `value` that lags one commit
`useDebouncedValue(value, delayMs)`	`value` after it stops changing for `delayMs`
`useThrottledValue(value, intervalMs)`	`value` at most once per `intervalMs` (leading+trailing)

useState‘s initial is by-name (evaluated once), giving lazy initialization through the same signature. Dependency arrays: Array(a, b) re-runs on change, Array() runs once, null runs every render. Effect cleanups return a function or noCleanup.

DOM hooks (built on the primitives, for common DOM patterns):

Hook	Does
`useEventListener(target, event, handler)`	Subscribe to a DOM event for the lifetime
`useClickOutside(ref, active, handler)`	Fire when a press lands outside `ref`
`useMediaQuery(query)`	Live `Boolean` for a CSS media query
`useIntersectionObserver(ref, …)`	`Boolean` viewport visibility (lazy load)

See Hooks.

The DSL

Elements — a function per HTML tag (div, p, ul, input, button, table, …) plus namespaced SVG (svg, path, …).
Children — String, Int, VNode, Seq[VNode], and Option[VNode] are all valid children via automatic conversions.
Attributes — AttrKey := value (cls/className, id, href, value, …); aria(name) / data(name) for the long tail; css(name -> value, …) for inline styles; enumerated booleans render "true"/"false".
Events — typed EventKey := handler (onClick, onInput, onKeyDown, …); on(name) for the rest; targetValue(e) reads an input’s value. Chain .capture, .once, and/or .passive for listener options (onScroll.passive := h).
Refs — ref := box binds an element to a useRef box (or a callback); pass a ref down as a prop to forward it, and useImperativeHandle to expose a custom handle.
Keys — key := id on an element (or a second arg to a component) for stable list identity.
Conditionals — when(cond)(node), unless(cond)(node).
Escape hatches — unsafeHtml(s), portal(target, child), errorBoundary(fallback)(child).

Context

createContext(default) makes a Context[T]; ctx.provide(value, child) scopes a value to a subtree; useContext(ctx) reads the nearest one.

Rendering

render(node, container) mounts a tree into a DOM element and returns a Root. Calling render again reconciles; root.unmount() tears down. createRoot(container) gives you the Root without an initial render.

riposte-atoms

Atomic, identity-based shared state built on the core’s useSyncExternalStore seam.

Create — atom(value) (primitive), atom(get => …) (derived, read-only), atom(read, write) (writable-derived), action(write) (write-only command).
Utilities — selectAtom, atomFamily, atomWithStorage, atomLoadable.
Hooks — useAtom (read+write), useAtomValue (read), useSetAtom (write).
Store — values live in a Store; Store.default is the global one, new Store makes a scoped one, StoreProvider(store) { … } scopes it to a subtree.

See State with Atoms.

riposte-router

Client-side routing built on the core’s public API.

Setup — Router(mode) { … }, mode = RouterMode.History (default) or RouterMode.Hash.
Routes — Routes(...), route(pattern)(view), nested children via route(...)(view)(children…), index(view), and Outlet for the matched child.
Navigation — Link(to, children…), NavLink(to, activeClass, end)(children…), navigate(to, replace).
Params & query — useParams() (a Map), useSearchParams() → (params, set).
Advanced — route(...).catchErrors(fallback), lazyView(load, fallback), ScrollRestoration().

See Routing.

riposte-salle

A styled component library on top of the core.

Skin system — components express intent (Color, Size, per-component variant enums like ButtonVariant); a Skin maps that to CSS classes. Ships SalleSkin (default, styled by salle.css) and DaisySkin (DaisyUI vocabulary). Set one with SkinProvider(skin) { … }; read it with useSkin().
Theming — one open data-theme set (ships light/dark, system follows the OS). useTheme() → (theme, resolved, setTheme, toggle); plus ThemeToggle (sun/moon icon button) and ThemeSelect(themes).
Components — Button, Input, Checkbox, Toggle, Select (Opt), ImageCard.
Layout — Row/Col (24-column grid, responsive spans) and Masonry / MasonryResponsive (packed columns; pure layoutMasonry).
Hook — useControllable(value, default, onChange) for controlled/uncontrolled state.

See Component library (salle).

Installation

2026-05-31T15:40:05.566249418Z

Riposte targets Scala.js. You need an sbt project with the Scala.js plugin enabled.

Requirements

Scala 3
sbt with the sbt-scalajs plugin
Node.js (for running and testing against a DOM via jsdom)

Add the plugin

In project/plugins.sbt:

addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.16.0")

Add the dependency

Riposte is published for Scala.js under the io.github.edadma organization. Enable the Scala.js plugin on your module and add the core library:

lazy val app = project
  .in(file("app"))
  .enablePlugins(ScalaJSPlugin)
  .settings(
    libraryDependencies += "io.github.edadma" %%% "riposte" % "0.0.2",
  )

The optional sibling artifacts are added the same way when you need them:

libraryDependencies += "io.github.edadma" %%% "riposte-atoms"  % "0.0.2"
libraryDependencies += "io.github.edadma" %%% "riposte-router" % "0.0.2"
libraryDependencies += "io.github.edadma" %%% "riposte-salle"  % "0.0.2"

All three depend on riposte transitively, so you do not need to list the core separately. (salle is the styled component library; it also ships a salle.css you include in your page.)

A DOM to render into

Riposte renders into a real DOM node. In the browser that is an element on the page; in tests it is a jsdom document. Configure the jsdom test environment in your build so tests have a DOM:

import org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv

Test / jsEnv := new JSDOMNodeJSEnv()

Continue to the quick start to mount a component.

Hooks

2026-05-31T15:40:05.566249418Z

Hooks give a component local state, side effects, memoized values, and access to the DOM. They’re available through a Hooks context that Riposte supplies while rendering — which is exactly what the component constructors (view, component, container) set up. Call hooks at the top level of a component body and you never pass the context explicitly:

import io.github.edadma.riposte.*

val Greeting = view {
  val (name, setName, _) = useState("world")
  div(
    input(value := name, onInput := (e => setName(targetValue(e)))),
    p(s"Hello, $name!"),
  )
}

The same is true inside component[P] { props => … } and container { children => … } — all three run their body with the Hooks context in scope.

The rules of hooks

Hooks are positional: Riposte identifies each one by its call order within a component, not by name. Two rules follow, and they’re the same as React’s:

Call hooks unconditionally, in the same order every render. Never put a hook inside an if, a loop, or a nested function — that would shift the positions on some renders and scramble the state. Put the condition inside the hook instead.
Call hooks only from a component body (or from another hook), not from ordinary functions.

// Wrong — the hook is conditional:
if loggedIn then val (x, setX, _) = useState(0)

// Right — the hook always runs; the condition lives in how you use it:
val (x, setX, _) = useState(0)
if loggedIn then …use x…

useState

useState(initial) returns a triple: the current value, a set that replaces it, and an update that derives the next value from the previous one.

val (count, set, update) = useState(0)

button(onClick := (_ => update(_ + 1)), s"Count: $count")   // increment
button(onClick := (_ => set(0)), "Reset")                   // replace

Reach for update whenever the next value depends on the current one — it composes correctly when several updates happen in the same event, where repeated set(count + 1) calls would all see the same stale count. Setters schedule a re-render on the microtask queue, so multiple updates in one event handler are batched into a single render.

The state can be any type — a Vector, a case class, whatever:

val (items, setItems, updateItems) = useState(Vector.empty[String])
updateItems(_ :+ "new")

The initial argument is by-name: it’s evaluated only on the first render, when the state cell is created, and never again. So an allocating initializer you don’t want re-run each render just works through the same signature — useState(new Buffer) builds the buffer once, not on every render. No separate “lazy initializer” form is needed.

useReducer

For state with several distinct transitions, useReducer centralizes them in one function. It returns the current state and a dispatch:

enum Action:
  case Increment, Decrement, Reset

val (count, dispatch) = useReducer[Int, Action](
  (state, action) => action match
    case Action.Increment => state + 1
    case Action.Decrement => state - 1
    case Action.Reset     => 0,
  0,
)

button(onClick := (_ => dispatch(Action.Increment)), s"Count: $count")

useEffect

useEffect(body, deps) runs a side effect after the DOM has been updated and the browser has painted (it runs on the macrotask queue, so it never blocks a frame). Use it for anything outside the render-to-DOM flow: network requests, subscriptions, timers, manual DOM measurement, logging.

The body returns a cleanup — either a function that undoes the effect, or noCleanup when there’s nothing to tear down. Riposte runs the cleanup before the effect re-runs and once more on unmount:

useEffect(
  () => {
    val id = dom.window.setInterval(() => tick(), 1000)
    () => dom.window.clearInterval(id)   // cleanup
  },
  Array(),                                // deps
)

The dependency array controls when the effect re-runs:

Array(a, b) — re-run only when a or b changed since the last render.
Array() (empty) — run once, after the first mount, and clean up on unmount.
null — run after every render.

useEffect(
  () => { dom.document.title = s"Count: $count"; noCleanup },
  Array(count),
)

useLayoutEffect has the same signature but runs synchronously after DOM mutations and before paint — use it (sparingly) when you must read layout and re-mutate the DOM without the user seeing an intermediate frame.

useRef

A ref is a mutable box whose .current survives across renders without causing a re-render when you change it. Two uses:

A handle to a DOM node. Bind it with the ref attribute, then reach for the node imperatively — the thing state can’t do:

val inputRef = useRef[dom.html.Input | Null](null)

div(
  input(ref := inputRef, placeholder := "press focus →"),
  button(
    onClick := { _ =>
      val node = inputRef.current
      if node != null then node.focus()
    },
    "focus",
  ),
)

ref also accepts a callback — ref := (node => …) — invoked with the node on mount and null on unmount, for when you need to react to attach/detach.

Mutable instance state that isn’t UI. A ref is the place for a value you want to remember but that shouldn’t trigger rendering — a previous value, a timer id, a flag.

useMemo and useCallback

Both cache something across renders, keyed on a dependency array, to avoid redundant work.

useMemo(compute, deps) caches the result of an expensive computation, recomputing only when a dependency changes:

val sorted = useMemo(() => items.sortBy(_.name), Array(items))

useCallback(fn, deps) caches a function value so its identity is stable across renders — important when you pass a handler to a memo-ized child (an inline lambda would be a new object each render and defeat the memoization) or use it as an effect dependency:

val onSelect = useCallback((id: String) => setSelected(id), Array())
Row(rowProps, onSelect)   // Row can now actually bail out

useId

useId() returns a stable, unique string id — the same value across re-renders of that instance. Use it to wire an input to its label without hand-managing globally unique ids:

val id = useId()
label(htmlFor := id, "Email")
input(id := id, `type` := "email")

useContext

Context passes a value down to descendants without threading it through every component’s props. Create a context with a default, provide a value to a subtree, and read the nearest provided value with useContext:

val ThemeContext = createContext("light")

val Themed = view {
  val theme = useContext(ThemeContext)
  div(cls := s"theme-$theme", "…")
}

// Provide a value to a subtree:
ThemeContext.provide("dark", Themed())

Reading a context subscribes the component to it: when a provider higher up supplies a new value, every descendant that reads the context re-renders. The atoms and router modules are both built on context.

useTransition

useTransition(target, durationMs) eases a Double toward target over durationMs, re-rendering the component each animation frame until it settles. It’s a self-driving animation primitive for simple numeric transitions — progress bars, fades, slides:

val (open, _, toggle) = useState(false)
val width = useTransition(if open then 100.0 else 0.0, 400)

div(
  css("width" -> s"$width%", "height" -> "0.5rem", "background" -> "#0c8599"),
  // a button elsewhere calls toggle(o => !o)
)

useSyncExternalStore

The low-level seam for subscribing a component to an external, mutable data source. You give it a subscribe function (called with a callback to run on change; returns an unsubscribe) and a getSnapshot that reads the current value:

val value = useSyncExternalStore(
  subscribe   = cb => { source.addListener(cb); () => source.removeListener(cb) },
  getSnapshot = () => source.current,
)

You rarely call this directly — it’s the foundation the atoms module and the router’s location tracking are built on. Reach for those higher-level APIs first; useSyncExternalStore is here for integrating a store Riposte doesn’t already wrap.

DOM hooks

A handful of higher-level hooks wrap common DOM patterns so you don’t re-implement the addEventListener/removeEventListener bookkeeping each time. They’re built on the primitives above and live in the core alongside them.

useEventListener(target, event, handler) attaches handler for event on target for the component’s lifetime, removing it on unmount. The latest handler is always used (it’s kept in a ref), so a handler closing over changing state stays current without re-subscribing every render:

useEventListener(dom.window, "resize", _ => recompute())

An overload takes EventListenerOptions(capture, passive, once), mirroring the DOM’s addEventListener options — e.g. passive = true to promise the handler won’t preventDefault (so the browser can scroll without waiting):

useEventListener(dom.window, "scroll", onScroll, EventListenerOptions(passive = true))

useClickOutside(ref, active, handler) calls handler when a pointer press lands outside the element held by ref, but only while active is true — the robust way to dismiss an open popup or menu (a real document pointerdown listener checking containment, not a focus-blur race):

val box = useRef[dom.Element | Null](null)
useClickOutside(box, menuOpen, () => setMenuOpen(false))
div(ref := box, /* … the menu … */)

useMediaQuery(query) returns a Boolean that tracks a CSS media query live — re-rendering when it starts or stops matching:

val isWide = useMediaQuery("(min-width: 768px)")
val prefersDark = useMediaQuery("(prefers-color-scheme: dark)")

useIntersectionObserver(ref, rootMargin, threshold, once) reports whether the element held by ref is in (or near) the viewport — for lazy loading and infinite scroll. It returns a Boolean that flips to true when the element intersects the viewport (expanded by rootMargin, default "200px", so work can start just before it scrolls in). With once = true (the default) it latches and disconnects — right for lazy-loading an image; with once = false it tracks visibility both ways. Where IntersectionObserver isn’t available it returns true, so dependent content still loads:

val tile = useRef[dom.Element | Null](null)
val visible = useIntersectionObserver(tile)
div(ref := tile, when(visible)(img(src := heavyImageUrl)))

(salle’s ImageCard is built on this hook.)

useResizeObserver(ref, onResize) calls onResize whenever the element held by ref changes size — the building block for any layout that recomputes when its container resizes (which a window resize listener misses: a sidebar opening, a flex sibling growing). Where ResizeObserver is unavailable it falls back to a window listener:

val box = useRef[dom.Element | Null](null)
useResizeObserver(box, () => remeasure())
div(ref := box, /* … */)

(salle’s Masonry measures with this hook.)

Rate-limiting a value

Three hooks derive a slower-changing copy of a fast-changing value, so expensive renders downstream don’t fire on every keystroke or scroll tick. Each returns a value of the same type:

useDeferredValue(value) lets the returned value lag the input — it catches up on a later macrotask when the main thread is idle, and a burst of updates collapses to the last one. For a search box driving a heavy results list, where you want the input itself to stay responsive.
useDebouncedValue(value, delayMs) updates only after delayMs of quiet — each new value resets the timer. For a query that should fire only once typing pauses.
useThrottledValue(value, intervalMs) updates at most once per intervalMs, always delivering the trailing value. For scroll/resize-driven state.

val (query, setQuery, _) = useState("")
val debounced = useDebouncedValue(query, 300)
// …a search effect keyed on `debounced`, not `query`
useEffect(() => { search(debounced); noCleanup }, Array(debounced))

useImperativeHandle

useImperativeHandle(ref, create, deps) populates a ref with a custom handle (rather than the raw DOM node), so a parent can call methods a child exposes — focus(), scroll, imperative form APIs. The handle is built after commit and rebuilt when deps change, and cleared on unmount so a parent never calls into an unmounted child:

// In the child, given a `ref: Ref[Controls | Null]` passed down as a prop:
useImperativeHandle(ref, () => new Controls { def focus() = inputRef.current.focus() }, Array())

Reach for it sparingly — most parent→child communication should be props, not method calls.

Components & the DSL

2026-05-31T15:40:05.566249418Z

A Riposte UI is an immutable tree of VNodes. You don’t build that tree by hand — you describe it with the DSL (element functions, attribute keys, event keys) and package reusable pieces of it as components. This page covers both: first how to describe markup, then how to factor it into components that take props and children.

Elements

Every HTML element has a function of the same name. Each takes a varargs list of modifiers — attributes, event handlers, and children, in any order:

import io.github.edadma.riposte.*

div(
  cls := "card",
  h2("Riposte"),
  p("A React-inspired library for Scala.js."),
)

The element functions cover the everyday HTML vocabulary — sectioning (section, article, nav, header, footer, main, aside), grouping (div, p, ul, ol, li, pre, blockquote, figure), text (span, a, strong, em, code, small, mark), forms (form, input, textarea, select, option, button, label), tables (table, thead, tbody, tr, th, td), and media (img, video, audio, source). SVG elements (svg, path, circle, g, …) are there too and are namespaced automatically.

Children

A child can be another element, a String (becomes a text node), or an Int (rendered as its decimal text). These conversions are automatic, so you can mix them freely:

p("You have ", strong(count), " unread messages.")

A Seq[VNode] is spliced in as a run of children — the idiom for rendering a list from data:

ul(
  items.map(item => li(item.name))
)

An Option[VNode] is also a valid child: Some(node) renders the node, None renders an empty placeholder (not nothing) so that toggling between the two keeps the surrounding siblings — and their state — in stable positions.

Attributes

Attributes are AttrKey values combined with a value through :=:

input(
  cls         := "field",
  id          := "email",
  value       := text,
  placeholder := "you@example.com",
  disabled    := submitting,        // Boolean
  tabIndex    := 0,                  // rendered as text
)

:= accepts a String, a Boolean, or a Double. cls (also available as className), id, href, src, value, name, type, placeholder, title, and the rest of the common attributes are provided as keys.

For attributes without a dedicated key, two families of helpers cover the long tail:

div(
  aria("label") := "Close",        // aria-label="Close"
  data("user-id") := userId,       // data-user-id="…"
)

Enumerated booleans — draggable, spellcheck, contenteditable, and the ARIA states — render the literal strings "true" / "false" rather than toggling by presence, which is what those attributes actually require.

Inline styles

css takes name -> value pairs and sets the style attribute:

div(
  css(
    "background"    -> "#0c8599",
    "height"        -> "0.75rem",
    "border-radius" -> "4px",
    "width"         -> s"$pct%",
  )
)

Events

Event handlers are EventKey values, also combined with :=. Each key is typed by the event it delivers, so the handler parameter needs no annotation — onClick hands you a dom.MouseEvent, onKeyDown a dom.KeyboardEvent, onInput a dom.Event:

button(onClick := (e => println(s"clicked at ${e.clientX}, ${e.clientY}")), "Click me")

input(onKeyDown := (e => if e.key == "Enter" then submit()))

The full set covers mouse, pointer, keyboard, focus, drag, touch, and clipboard events. For an event without a dedicated key, on(name) gives you a handler typed as the base dom.Event. Reading the current value of an <input> is common enough to have a helper:

input(value := draft, onInput := (e => setDraft(targetValue(e))))

Components

A component is a reusable, named piece of UI. It’s an ordinary val, built with one of three constructors depending on what it accepts. You call it — Counter(), Stat("Clicks", n) — wherever a child is expected, and the result is a VNode like any other.

Components matter for more than reuse: the reconciler tracks each mounted component by identity, so hook state (see Hooks) lives on the instance and survives re-renders, and only the components whose inputs changed re-render.

`view` — no props

The simplest component takes nothing. Build it with view { … }; the block is the render body, and hooks work inside it:

val Counter = view {
  val (count, _, update) = useState(0)
  button(onClick := (_ => update(_ + 1)), s"Count: $count")
}

Call it with empty parens — Counter() — to get a node:

div(h1("Demo"), Counter())

`component` — props

When a component needs inputs, build it with component. The one-prop form takes a single value:

val Greeting = component[String] { name =>
  p(s"Hello, $name!")
}

Greeting("world")

For several inputs, the positional forms (component[A, B], up to four) let you pass arguments directly instead of bundling them:

val Stat = component[String, Int] { (label, value) =>
  div(
    cls := "stat",
    span(cls := "label", label),
    span(": "),
    strong(value),
  )
}

Stat("Clicks", clicks)
Stat("Likes", likes)

If you’d rather have named fields without declaring a case class, pass a single named tuple to component[P]:

val Card = component[(title: String, count: Int)] { p =>
  div(span(p.title), strong(p.count))
}

Card((title = "Unread", count = 12))

A parent re-renders its children by passing them new props; each child re-renders only when the props it received actually changed.

`container` — children (slots)

A component that wraps arbitrary children — the analogue of React’s props.children — is built with container. The children arrive as a Children (a Vector[VNode]); splice them wherever you like with the usual seq-as-children conversion:

val Card = container { children =>
  div(cls := "card", children)
}

Card(
  h2("Title"),
  p("Body text."),
)

A container can take props and children. Declare it with container[P] and call it curried — props first, then the children:

val Panel = container[(title: String)] { (p, children) =>
  section(
    cls := "panel",
    h2(p.title),
    div(cls := "panel-body", children),
  )
}

Panel((title = "Settings"))(
  toggle,
  slider,
)

Keyed lists

When you render a list that can reorder, insert, or delete, give each item a stable key so the reconciler moves DOM nodes instead of rebuilding them — preserving their state and focus. Inside an element, set it with the key attribute:

ul(
  items.map(item =>
    li(
      key := item.id,
      span(item.name),
      button(onClick := (_ => remove(item.id)), "✕"),
    )
  )
)

A component instance can be keyed too, by passing a key as the second argument: Row(rowProps, item.id).

`memo` — skip unchanged re-renders

Wrapping a component in memo makes it bail out of a parent-driven re-render when its new props are equal (==) to the previous ones — Riposte’s React.memo. It still re-renders on its own state changes:

val Row = memo(component[RowProps] { props => … })

Define the memoized component once as a stable val; calling memo inline in a render produces a new identity each time and defeats the purpose. Props that carry freshly allocated closures compare unequal every render, so stabilize handlers with useCallback (see Hooks) when memoizing.

Escape hatches

A few constructs step outside the normal element-tree flow:

unsafeHtml(s) sets an element’s inner HTML directly — Riposte’s dangerouslySetInnerHTML. Only pass markup you trust.
portal(target, child) renders child into a different DOM node (one outside the component’s own subtree) while keeping it logically part of the tree — for modals, tooltips, and overlays that must escape overflow: hidden or stacking contexts.
errorBoundary(fallback)(child) catches throws during child‘s mount, patch, and re-render, rendering fallback(error) in its place instead of tearing down the whole tree.

errorBoundary(err => div(cls := "error", s"Something broke: ${err.getMessage}")) {
  RiskyWidget()
}

Continue to Hooks for state, effects, and the rest of the hook family.

Riposte

State with Atoms

Atoms

Using atoms in components

Stores and scoping

More atom kinds

Component library (salle)

The skin system

Light & dark theming

The style vocabulary

Components

Button

Input

Checkbox and Toggle

Select

ImageCard

Layout

Grid (Row / Col)

Masonry

useControllable

Theming the default look

Routing

A router and some routes

History vs. hash mode

Params

Links and navigation

Nested routes

Query strings

Per-route error boundaries

Lazy routes

Scroll restoration

Quick Start

Describe the UI

Mount it

Where to go next

Modules & API

riposte (core)

Components

Hooks

The DSL

Context

Rendering

riposte-atoms

riposte-router

riposte-salle

Installation

Requirements

Add the plugin

Add the dependency

A DOM to render into

Hooks

The rules of hooks

useState

useReducer

useEffect

useRef

useMemo and useCallback

useId

useContext

useTransition

useSyncExternalStore

DOM hooks

Rate-limiting a value

useImperativeHandle

Components & the DSL

Elements

Children

Attributes

Inline styles

Events

Components

view — no props

component — props

container — children (slots)

Keyed lists

memo — skip unchanged re-renders

Escape hatches

`view` — no props

`component` — props

`container` — children (slots)

`memo` — skip unchanged re-renders