# The pattern catalog — every construct, on a real problem
One pattern per real-world problem, organized by what you're building. Each: the problem, the
construct, what it replaces. New here? Do the [tutorial](https://github.com/AleSaiani/ResponsiveJS/blob/main/tutorial.md) first — it builds a
page with the core patterns. Three of the entries below are also
[unpacked end to end](#deep-dives) (DOM before/after, the measurement, the test).
## Navigation & page chrome
### The burger that appears exactly when needed — `whenWraps`
Replaces: the hand-tuned `@media (max-width: 843px)` that rots when a link is added or the
site is translated.
```typescript
r$.geometry('.site-nav', { wrapped: r$.whenWraps });
```
```css
.site-nav[data-wrapped] { visibility: hidden; height: 0; overflow: hidden; }
.site-nav[data-wrapped] ~ .menu-button { display: block; }
```
[Full anatomy below](#deep-dive-1--the-burger-menu-whenwraps). Rule: collapse *keeping
layout* — never `display: none` what a predicate measures.
### Toolbar "More…" overflow — `whenOverflows`
Replaces: guessing how many toolbar buttons fit at which width.
```typescript
r$.geometry('.toolbar', { crowded: r$.whenOverflows() });
```
```css
.toolbar { overflow: hidden; }
.toolbar[data-crowded] ~ .more-menu-button { display: inline-flex; }
```
The "More…" button exists exactly while content exceeds the box.
### Header effects only while pinned — `whenStuck`
Replaces: the IntersectionObserver-sentinel hack. `r$.geometry('.site-header', { stuck:
r$.whenStuck() })` → `.site-header[data-stuck] { box-shadow: …; }` — shadow, condensed logo,
blur: anything, only while actually stuck. [Full anatomy below](#deep-dive-2--header-effects-only-while-pinned-whenstuck).
## Content
### "Read more" only when something was cut — `whenTruncated`
Replaces: character-count heuristics that break with fonts, widths, languages.
`r$.geometry('.excerpt', { truncated: r$.whenTruncated() })` →
`.excerpt[data-truncated] + .read-more { display: inline; }`.
[Full anatomy below](#deep-dive-3--read-more-only-when-truncated-whentruncated).
### Layout that reacts to line count — `linesOf`
Replaces: nothing — this wasn't feasible. A heading that centers when it fits on one line,
left-aligns when it wraps:
```typescript
r$.geometry('.card h2', { lines: r$.linesOf() }); // → data-lines="1" | "2" | …
```
```css
.card h2[data-lines='1'] { text-align: center; }
```
### The carousel scroll affordance — `whenOverflows('x')`
Show the "scroll →" hint only while there IS more content:
```typescript
r$.geometry('.chip-row', { scrollable: r$.whenOverflows('x') });
```
```css
.chip-row[data-scrollable]::after { content: '→'; /* fade gradient, arrow, anything */ }
```
## Relations between elements
### Equal heights across unrelated containers — `sync`
Replaces: subgrid (when the DOM allows it) or hand-rolled measure loops with stale-value
bugs. `r$.sync('.card h3', 'height')` — max natural height wins, re-synced on resize,
restored on dispose. Call `handle.measure()` after swapping content dynamically.
### A layout invariant, enforced — `ratio`
Replaces: hoping the CSS holds. `r$.ratio('.sidebar', '.main', { min: 0.2, max: 0.33 })` —
inside the bounds the layout flows free; outside them the sidebar is pinned to the boundary.
This is the validation constraint `proportion` promoted to runtime *enforcement*: author and
verifier speak the same rule.
### A value driven by ANOTHER element — `fromElement`
Replaces: nothing — container queries only see ancestors.
```typescript
r$('.main-content', {
fontSize: r$.fluid(14, 18, { domain: r$.fromElement('.sidebar'), from: 200, to: 400 }),
});
```
Master-detail panes, editors whose type tracks the preview pane, anything where element A
answers to element B's size.
### Floating UI that yields to content — `whenCollides`
```typescript
r$.geometry('.floating-cta', { overlapping: r$.whenCollides('.footer') });
```
```css
.floating-cta[data-overlapping] { opacity: 0.15; pointer-events: none; }
```
The FAB fades exactly while it covers the footer — measured, not scripted to scroll offsets.
## Fluid values & the design system
### The type scale with character — curves
Linear is free (static `clamp()`); when linear feels flat, shape the growth:
```typescript
r$.tokens({
'--font-hero': r$.fluid(28, 64, { curve: 'exponential' }), // restrained on mobile, dramatic on wide
'--font-body': r$.fluid(15, 18), // linear → zero JS
});
```
### Per-breakpoint values without the ladder — `fluid([...])`
`r$.fluid([12, 16, 24, 32])` places one value per configured breakpoint and interpolates the
segments — the multi-stop scale as one expression, still statically compiled where linear.
### Perceptual color transitions — `fluid(color, color)`
`r$.fluid('#1a1a2e', '#4a4a6a')` interpolates in OKLab — no gray dead-zone in the middle
(the classic sRGB-mix artifact). Backgrounds that lighten as the viewport grows, borders that
soften: `color: r$.fluid('#111', '#555')`.
### Themes and design tokens as a pipeline — `tokens` + DTCG
The scale lives in one place, CSS consumes `var()` everywhere, themes are alternative token
sets — and `handle.toDTCG()` exports the whole system (curves sampled per breakpoint) as
Design Tokens Community Group JSON for Figma/Style Dictionary pipelines. `handle.css` is the
SSR stylesheet.
### Container-aware components — `{ container: true }`
`r$.fluid(14, 18, { container: true, from: 240, to: 820 })` binds to the nearest container instead of the
viewport (static output uses `cqi`; the handle configures `container-type` on the parent,
refcounted). The same card component sizes correctly in a sidebar and in the main column.
**`from`/`to` are required here, and that is deliberate.** `container: true` changes *what is
measured*, not the domain the value is interpolated over. Left implicit it would use your
viewport breakpoints, so a card that lives between 240px and 820px inside a `[320, 1440]`
project would walk a fifth of its own curve — and the symptom is "the library does nothing".
r$ refuses to build such a value and tells you what to write:
```ts
const panel = { container: true, from: 240, to: 820 }; // the container's real range
r$('.card', {
fontSize: r$.fluid(15, 26, panel),
padding: r$.fluid(10, 30, panel),
});
```
There is no rule of thumb to remember: if a value is bound to a container, `from`/`to` are the
other half of the declaration, and leaving them out is a construction-time error.
## Styling any property
The style map takes **any** CSS property (camelCase), and `fluid` is polymorphic — numbers,
colors, structured strings. These patterns show the range on real problems.
### The hero that sets a mood — background color ramps
Problem: on a phone the hero must be quiet and readable; on a cinema display it can be
atmospheric. Discrete theme swaps at a breakpoint look like a glitch.
```typescript
r$('.hero', {
backgroundColor: r$.fluid('#16181d', '#1e2340'), // deepens as space grows
color: r$.fluid('#e8e8e8', '#ffffff'),
});
```
Interpolation runs in OKLab — no gray dead-zone mid-ramp (the classic sRGB artifact). Any
color property works: `borderColor`, `outlineColor`, `caretColor`.
### Depth that grows with space — fluid shadows
Problem: design systems scale elevation in steps (sm/md/lg) and pick one per breakpoint;
cards jump between flat and floating. Structured-string interpolation makes elevation
continuous — numbers *and* the shadow color interpolate together:
```typescript
r$('.card', {
boxShadow: r$.fluid('0 1px 3px rgba(0,0,0,0.30)', '0 16px 48px rgba(0,0,0,0.18)'),
borderRadius: r$.fluid(8, 16),
});
```
Mobile: tight, dark, close to the surface. Desktop: soft, wide, floating. Same works for
`filter: blur(…)`, `textShadow` — any congruent value string.
### Presence without reflow — fluid transforms
Problem: a decorative element should be subtler on small screens, but animating `width`
causes reflow. Transforms are compositor-only:
```typescript
import { combine, scale, rotate } from '@responsivejs/runtime';
r$('.hero-badge', {
transform: combine([scale(r$.fluid(0.85, 1.15)), rotate(r$.fluid(-2, -6, 'deg'))]),
});
```
### Density as a system — the dashboard ramp
Problem: dashboards need to be dense on laptops and breathable on big monitors — usually
solved by a "compact mode" toggle users must find. Make density a *function of space*
instead, in one place:
```typescript
r$.tokens({
'--cell-pad': r$.fluid(6, 14),
'--row-gap': r$.fluid(4, 10),
'--font-data': r$.fluid(12.5, 15),
});
```
```css
td { padding: var(--cell-pad); font-size: var(--font-data); }
tr { margin-block: var(--row-gap); }
```
Every table, list and card in the app breathes together — and the whole ramp is one token
block you can hand to design as DTCG.
### Structure switching — the adaptive side
When the change is *structural* (an in-between value means nothing), switch discretely —
plain-value branches compile to static `@media`:
```typescript
const bp = r$.breakpoints({ mobile: 320, tablet: 768, desktop: 1280 } as const);
r$('.filters', { flexDirection: bp.below('tablet', 'column', 'row') });
r$('.sidebar', { display: bp.below('tablet', 'none', 'block') });
```
And the regimes mix: a switch's branches can hold fluid values, so each regime stays fluid
inside its range. When to flow vs when to switch — and when the trigger should be geometric
rather than a width — is the [responsive-or-adaptive framework](runtime#responsive-or-adaptive-choosing-the-mechanism)
in the guide.
## Lifecycle & environments
### SPA components — keep the handle
Every construct returns a handle; tie it to unmount and everything is undone *and restored*:
```typescript
useEffect(() => {
const nav = r$.geometry(ref.current!, { wrapped: r$.whenWraps });
return () => nav.dispose();
}, []);
```
Note: selectors resolve at creation — for elements mounted later, create the construct in the
component that owns them — or let an [adapter](../api/adapters) do it for you
(React, Vue and Angular bindings own the lifecycle), or `r$.scope()` to release a group at once.
### SSR without flashes — static emission
Linear constructs never needed JS: ship `r$.tokens(...).css` / `r$.static(selector, map).css` as
server-rendered CSS; geometry attributes hydrate on the client (constructs are inert without
`window`). The page is correct before a single byte of JS runs.
---
# Deep dives
Three of the patterns above, unpacked completely: the HTML, what the predicate measures, the
exact DOM before/after, why the CSS is shaped that way, and the test.
## Deep dive 1 — The burger menu (`whenWraps`)
### The situation
A header with a logo, six nav links, and a burger button that should appear **only when the
links no longer fit on one line**:
```html
r$
```
The classic solution is `@media (max-width: 843px)` — where 843 is whatever width the links
happened to overflow at the day you wrote it. Add a link, rename one, translate the site to
German, and 843 is silently wrong.
### What `whenWraps` actually does
`whenWraps` is a **measurement**, nothing more: given an element, it reads the rectangles of
its children and answers one question — *does any child start below the first row?*
```
one row (fits): two rows (wrapped):
[Model][Authoring]…[Docs] [Model][Authoring][Validation]
[Contracts][Agents][Docs]
all tops equal → false a child's top ≥ first child's bottom → true
```
You can call it yourself, one-shot, no wiring — this is worth trying in a console to demystify
it:
```typescript
r$.whenWraps().measure(document.querySelector('.site-nav')); // → true | false
```
### What `geometry()` adds
`geometry()` turns that one-shot measurement into a **maintained fact on the DOM**:
```typescript
r$.geometry('.site-nav', { wrapped: r$.whenWraps });
```
From this line on, r$ re-runs the measurement whenever it could change — the nav resizes
(one shared ResizeObserver), the viewport resizes — and mirrors the answer into an attribute.
Concretely, this is the *only* thing it does to your DOM:
```html
```
No styles are touched, no classes added, nothing hidden. The key you chose (`wrapped`)
becomes the attribute name (`data-wrapped`).
### The CSS reacts
Styling is entirely yours, in the stylesheet, keyed on that attribute:
```css
/* collapsed nav: hidden but STILL LAID OUT (see the rule below) */
.site-nav[data-wrapped] {
visibility: hidden;
height: 0;
overflow: hidden;
}
.site-nav[data-wrapped] ~ .menu-button {
display: block;
}
```
Why `visibility: hidden; height: 0` and **not** `display: none`: the predicate must keep
measuring the nav to know when to un-wrap. `display: none` gives every child a 0×0 rect, so
the measurement would flip back to "not wrapped", the nav would reappear, wrap again — an
oscillation. Collapsing *while keeping layout* makes the state stable. This is the one rule
of geometry; it will fail loudly in front of you the first time you forget it, and now you
know why.
### Seeing it work
Open the page, open devtools on the `