When

A tiny library for generating declarative conditional-rendering components, inspired by react-display-switch.

Generate When / WhenNot components from an arbitrary set of conditions, and combine them with and / or to toggle what is displayed.

• https://www.npmjs.com/package/@synpuls/when

Installation

npm install @synpuls/when

react (>=18) is a peer dependency.

Usage

import { useState } from 'react'
import { createWhen } from '@synpuls/when'

// A trivial "store". Conditions are plain `() => boolean` predicates,
// so they can read from anywhere in scope.
const store = { user: null as { role: string } | null }

// Register your conditions once.
const { When, WhenNot } = createWhen({
  isLoggedIn: () => store.user !== null,
  isAdmin: () => store.user?.role === 'admin',
})

const App = () => {
  // Conditions are re-evaluated on every render, so trigger a re-render
  // (here via state) after the data they read changes.
  const [, forceRender] = useState(0)
  const signInAsAdmin = () => {
    store.user = { role: 'admin' }
    forceRender((n) => n + 1)
  }

  return (
    <>
      <When isLoggedIn>Welcome back!</When>
      <WhenNot isLoggedIn>
        <button onClick={signInAsAdmin}>Sign in</button>
      </WhenNot>

      {/* Multiple conditions require an explicit `and` / `or` */}
      <When isLoggedIn and isAdmin>
        Admin dashboard
      </When>
    </>
  )
}

Case props are boolean flags — write <When isLoggedIn> (equivalent to isLoggedIn={true}). You can also read a condition's current value directly with When.case('isLoggedIn').

API

• createWhen(cases) — build { When, WhenNot } from a condition map. Requires at least one condition.
• When / WhenNot — show / hide children based on the conditions. WhenNot renders the logical negation of When.
  • Passing multiple conditions requires an explicit and or or (they are mutually exclusive).
  • When.case(label) returns the condition's current boolean; When.cases exposes the (frozen) registered map.
• children, and, or are reserved and cannot be used as condition labels.

Behavior & limitations

• Evaluated on render, not subscribed. Conditions are re-run every time the component renders; the library does not subscribe to external sources. To reflect a change (viewport size, store, etc.), make sure something triggers a re-render, and keep predicates side-effect-free and cheap. For viewport-based conditions, read from React state fed by a listener rather than calling window.matchMedia directly inside a predicate (which is also not SSR-safe).
• Flat, single operator only. You can express a and b and c or a or b or c, but not mixed logic like (a and b) or c. Compose complex conditions in createWhen instead, e.g. phonePortrait: () => isPhone() && isPortrait().
• true-only flags. Case props and and / or accept only true (or omission); the types reject non-true values at compile time. Passing a non-true value to a case prop throws at runtime. For and / or, a non-true value is treated as "not specified" (so multiple cases without an effective operator still throw "must specify an operator").

Development

npm run typecheck   # type check (includes *.test-d.tsx type tests)
npm test            # tests (vitest)
npm run lint        # lint / format check (biome)
npm run format      # auto-fix
npm run build       # generate dist (tsup)

License

MIT