reflow

SSR-safe responsive toolkit for TypeScript. One API, every framework.

npm install reflow

Try it live:

Reflow gives you breakpoints, container queries, fluid typography, viewport tracking, and user preference detection in one library. It works in React, Vue, Svelte, Solid, Qwik, Preact, Lit, Angular, and plain JS. No hydration mismatch warnings. No typeof window checks scattered everywhere.

One import. One type system. Zero framework lock-in.

import { ResponsiveProvider, useBreakpoint, useResponsiveValue, Show } from "reflow/react";
import { fluidClamp } from "reflow/styles";

function App() {
  const bp = useBreakpoint();
  const cols = useResponsiveValue({ xs: 1, md: 2, xl: 4 });

  return (
    <main style={{ fontSize: fluidClamp({ minPx: 16, maxPx: 22 }) }}>
      <p>Breakpoint: {bp.active}</p>
      <Grid columns={cols} />
      <Show above="md">
        <Sidebar />
      </Show>
      <Show below="md" fallback={<DesktopNav />}>
        <MobileMenu />
      </Show>
    </main>
  );
}

export default () => (
  <ResponsiveProvider serverWidth={1024}>
    <App />
  </ResponsiveProvider>
);

<script setup lang="ts">
import { useBreakpoint } from "reflow/vue";
const bp = useBreakpoint();
</script>

<template>
  <FullNav v-if="bp.above('desktop')" />
  <HamburgerMenu v-else />
</template>

<script>
  import { breakpoint } from "reflow/svelte";
  const bp = breakpoint();
</script>

{#if $bp === 'desktop'}
  <FullNav />
{:else}
  <HamburgerMenu />
{/if}

import { createBreakpoints, observeViewport } from "reflow";

const bp = createBreakpoints({ sm: 640, md: 768, lg: 1024 } as const);

const unsub = observeViewport(({ width }) => {
  console.log(bp.resolve(width));
});

unsub();

All adapters share the same framework-agnostic core. React, Vue, and Svelte ship dedicated entry points. Everything else uses the core directly.

Most responsive libraries do one thing. A media query hook here, a viewport hook there, a fluid type calculator somewhere else. You end up with 5 packages, overlapping logic, and hydration errors to debug.

Reflow puts it all in one place:

• SSR-safe by default. Every hook uses useSyncExternalStore with getServerSnapshot. Pair with <ResponsiveProvider serverWidth={...}> for correct first paint.
• Typed breakpoints. createBreakpoints({ sm: 640, md: 768 } as const) gives you literal-typed keys with full autocomplete.
• Fluid typography. fluidClamp() generates CSS clamp() at runtime. No more copy-pasting from utopia.fyi.
• Container queries. ResizeObserver-based, no polyfill needed. Works in any framework.
• User preferences. prefers-reduced-motion, prefers-reduced-data, prefers-contrast, forced-colors, inverted-colors. All typed, all SSR-safe.
• Server rendering. resolveBreakpointFromHints(headers) reads Client Hints with UA fallback. Works with Next.js, Hono, Express, anything.
• Zero framework lock-in. Core has no React dependency. Use it in Vue, Svelte, Solid, or plain JS.

See the full comparison against react-responsive, @vueuse/core, and usehooks-ts.

import { headers } from "next/headers";
import { resolveBreakpointFromHints } from "reflow/server";
import { ResponsiveProvider } from "reflow/react";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const h = await headers();
  const { width } = resolveBreakpointFromHints(h);

  return (
    <ResponsiveProvider serverWidth={width}>
      {children}
    </ResponsiveProvider>
  );
}

import { resolveServerBreakpoint, clientHintsResponseHeaders } from "reflow/server";

app.use((req, res, next) => {
  for (const [key, value] of clientHintsResponseHeaders) {
    res.setHeader(key, value);
  }
  next();
});

app.get("/", (req, res) => {
  const { breakpoint, width } = resolveServerBreakpoint(req.headers);
});

Enforced in CI via size-limit. Every PR that exceeds the budget fails.

Reflow ships test utilities so your component tests don't need a real browser:

import { installMatchMediaMock, installResizeObserverMock, setWindowSize } from "reflow/testing";

const matchMedia = installMatchMediaMock();
const resizeObserver = installResizeObserverMock();

setWindowSize(768, 1024);
matchMedia.set("(prefers-color-scheme: dark)", true);
resizeObserver.resize(element, { width: 500, height: 300 });

Full API docs are in the source. Each module exports typed functions with JSDoc. Here are the main ones:

Container queries require Safari 16+, Chromium 105+, Firefox 110+. prefers-reduced-data is Chromium-only and gracefully returns false elsewhere.

git clone https://github.com/valtors/reflow && cd reflow
npm install
npm run verify   # typecheck + lint + test + build + publint + attw + size

Shipped:

• Core responsive primitives (breakpoints, viewport, container, media, preferences)
• React, Vue, Svelte, Solid, Qwik, Preact, Angular, Lit adapters
• Fluid typography helpers
• Server-side rendering utilities
• Tailwind preset
• Test utilities
• CI with typecheck, lint, test, build, publint, attw, size-limit
• Throttle/debounce support on viewport and container observers

Next:

• Custom hook generators (define your own responsive hooks from config)
• DevTools browser extension
• More framework-specific examples and starter templates
• Migration guides from react-responsive, @vueuse/core, usehooks-ts

Check CONTRIBUTING.md for the full guide. Look for good first issue labels to get started.

We follow the Contributor Covenant.

MIT (c) Tamish Mhatre

If reflow saves you time, star the repo.

Relay - a local-first MCP server with 40+ tools for file ops, web fetch, screenshots, agent memory, and more. Same org, same philosophy: boring tech that just works.

If reflow helps your work, consider giving it a star. It helps others discover it.