Deterministic conditional rendering for React. Render exactly one option from multiple independent conditions, with explicit priority and fail-fast guarantees.
npm install react-super-switchA small React utility component for deterministic, readable, and safe conditional rendering.
react-super-switch guarantees that exactly one view is rendered from a set of mutually exclusive options, even when conditions are complex, unrelated, or derived from business logic.
!npm version
!gzip size
!dependencies
!react
!typescript
!tree-shakeable
react-super-switch is designed to be extremely lightweight.
- ESM bundle: ~10 KB raw / <= 1KB minified + gzipped
- CJS bundle: ~7.2 KB raw / <= 1KB minified + gzipped
- Dependencies: none
Only the selected bundle format is included in your production build; TypeScript types and other metadata are not shipped to users.
Conditional rendering in React often starts simple and slowly becomes hard to reason about.
``tsx`
return (
<>
{caseA &&
{caseB &&
{caseC &&
{caseD &&
);
This pattern has several issues:
- Multiple views can accidentally render at the same time
- Ordering and priority are implicit and fragile
- Negating conditions quickly becomes unreadable
- Refactors are risky and hard to review
- React Fragments are often required just to make JSX valid
- React does not support switch or if / else directly in JSX
As business logic grows, correctness and readability degrade fast.
React Super Switch introduces a declarative, safe alternative:
- Exactly one option is rendered
- Conditions are clearly scoped
- Priority is explicit (optional)
- A default fallback can be defined
Invalid configurations fail loudly during development
`bash`
npm install react-super-switch
- React 17 or newer
- react and react-dom are peer dependencies
- No runtime Node.js requirement for consumers
`tsx`
import { SuperSwitch, Option } from "react-super-switch";
> The package exposes named exports only.
`tsx`
return (
<>
{businessCaseA &&
{businessCaseB &&
{businessCaseC &&
{businessCaseD &&
);
`tsx
return (
);
`
Only one will ever render.
The parent component that evaluates all children and decides which one to render.
`tsx`
| Prop | Type | Default | Description |
| ---------- | ------------------------ | -------- | --------------------------------------------------------------------------- |
| mode | "fcfs" or "priority" | "fcfs" | Determines how options are evaluated |optional
| | boolean | false | Allows the switch to render nothing when all Option conditions are falsy. |
Represents a single renderable branch.
`tsx`
| Prop | Type | Required | Description |
| ------------- | ----------- | -------- | ---------------------------------------- |
| condition | boolean | ❌ | Whether this option is eligible |priority
| | number | ❌ | Ordering hint (lower = higher priority) |data-testid
| | string | ❌ | A unique identifier for testing purposes |default
| | boolean | ❌ | Fallback option if no conditions match |children
| | ReactNode | ✅ | Rendered when this option is selected |
#### 1. fcfs (First-Come-First-Served) — default
Options are evaluated in JSX order.
- The first option with a truthy condition wins
- If no conditions match, the first default option is rendered
- priority is ignored
`tsx`
Use this mode when visual order already represents priority.
#### 2. priority
Options are evaluated by explicit priority.
- All elements must define priority
- Lower numbers mean higher priority ( beats 2)
- Order in JSX does not matter
- Default options are still supported
`tsx`
Use this mode when:
- Business rules are complex
- Priority changes frequently
- You want cleaner diffs and safer refactors
- At most one option is rendered
- If no conditions match:
- the first default option is rendered
- If no default exists, an error is thrown
`tsx`
{/ ❌ not allowed /}
`tsx`
`tsx`
{" "}
{/ ❌ missing priority /}
- When rendering logic depends on multiple independent conditions
- When only one view must ever render
- When priority must be explicit and reviewable
- When you want fail-fast behaviour instead of silent bugs
- Simple ternaries
- Binary conditions (if / else)
- List rendering (map)
There are a few existing React libraries that aim to improve conditional rendering.
They are useful in certain scenarios, but they solve a different class of problems
than react-super-switch.
The goal of this library is deterministic, exclusive rendering with explicit
prioritisation and fail-fast guarantees.
---
react-switch provides a JSX-friendly abstraction similar to a switch / case
statement.
What it’s good at:
- Cleaner syntax than inline && expressionsswitch
- Familiar -like mental model
Limitations:
- Multiple cases can render at the same time
- No priority or ordering guarantees
- No enforced default or fallback
- No runtime validation
react-switch assumes conditions are mutually exclusive, but does not enforce that
assumption.
---
react-if models imperative if / else if / else logic in JSX.
What it’s good at:
- Simple, linear conditional flows
- Readable for small, sequential branches
Limitations:
- Conditions must be logically chained
- No concept of independent business rules
- No priority system
- Does not guarantee that only one branch renders
This approach works well for simple control flow, but becomes hard to maintain when
conditions are unrelated or derived from complex business logic.
---
react-if-vz is conceptually closer to react-super-switch and attempts to introduce
more structured conditional rendering.
Limitations:
- Largely unmaintained
- Weak TypeScript support
- No enforced exclusivity
- Priority is implicit rather than guaranteed
- No fail-fast validation
---
react-super-switch focuses on correctness and intent, not just syntax:
- Exactly one option is rendered, or an error is thrown
- Priority is a first-class concept
- Default behaviour is explicit and enforced
- Invalid configurations fail loudly during development
- JSX remains clean and declarative
If your rendering logic depends on multiple independent conditions and only one
view must ever render, react-super-switch` is designed specifically for that use case.
MIT