npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@jsdevlab/react-headless

v1.1.1

Published

Type-safe headless logic components for React 19.

Readme

@jsdevlab/react-headless

Type-safe headless logic components for React 19. Every component is style-free, renders no wrapper DOM of its own, and works in both client and server components.

Installation

pnpm add @jsdevlab/react-headless react react-dom

React 19 and React DOM 19 are peer dependencies. React DOM is used by Portal.

Components

For

Render a list and infer the item type from each.

import { For } from '@jsdevlab/react-headless';

<For
  each={users}
  keyBy={(user) => user.id}
  filter={(user) => user.active}
  fallback={<Empty />}
>
  {(user, index) => <UserRow user={user} index={index} />}
</For>;
  • each — a readonly array of items.
  • children — (item, index) => ReactNode.
  • filter — optional predicate. fallback is rendered when the filtered list is empty.
  • fallback — rendered when the list is empty.
  • keyBy — derives a stable React key. Defaults to the item index.

For wraps each item in a keyed fragment and renders no DOM of its own.

Repeat / Range

import { Range, Repeat } from '@jsdevlab/react-headless';

<Repeat times={3}>{(index) => <Skeleton key={index} />}</Repeat>;

<Range from={1} to={5} step={1}>
  {(value) => <Dot key={value} />}
</Range>;
  • Repeat renders children times times with a zero-based index. Non-finite and non-positive values render fallback.
  • Range renders values from from (inclusive) to to (exclusive). A negative step iterates downwards; empty or invalid ranges render fallback.

Show / When / Unless / Not

import { Not, Show, Unless, When } from '@jsdevlab/react-headless';

<Show when={isLoading} fallback={<Content />}>
  <Spinner />
</Show>;

<When when={() => permissions.canEdit}>
  <Editor />
</When>;

<Unless when={isLoading}>
  <Content />
</Unless>;

<Not condition={isLoading} fallback={<Content />}>
  <Spinner />
</Not>;
  • A condition can be a boolean or a lazy () => boolean function.
  • children and fallback accept either a ReactNode or a lazy render function.
  • When is an alias of Show.
  • Unless renders its children when the condition is false.
  • Not is a convenience wrapper around Unless.

With

import { With } from '@jsdevlab/react-headless';

<With value={user} fallback={<SignIn />}>
  {(user) => <Profile user={user} />}
</With>;

With renders its children when value is present and narrows the value type for the render function. false, null, and undefined are absent; 0 and '' are present.

Every / Some / None

import { Every, None, Some } from '@jsdevlab/react-headless';

<Every conditions={[isReady, () => permissions.canEdit]}>
  <Editor />
</Every>;

<Some conditions={[isAdmin, isOwner]} fallback={<ReadOnly />}>
  <Toolbar />
</Some>;

<None conditions={[isLoading, hasError]} fallback={<Spinner />}>
  <Content />
</None>;
  • Each condition can be a boolean or a lazy () => boolean function.
  • Every requires all conditions to be true.
  • Some requires at least one condition to be true.
  • None requires all conditions to be false.

Switch / Case / Default

import { Case, Default, Switch } from '@jsdevlab/react-headless';

<Switch value={status} fallback={<Unknown />}>
  <Case value="loading">
    <Spinner />
  </Case>
  <Case value={['ready', 'idle']}>
    <Content />
  </Case>
  <Case value={(value) => value.startsWith('error')}>
    {(value) => <ErrorView code={value} />}
  </Case>
  <Default>
    <Empty />
  </Default>
</Switch>;
  • Switch matches Case branches against value using Object.is.
  • A Case value can be a single value, an array of values, or a predicate function (value) => boolean.
  • Case children and Default children can be render functions. Case render functions receive the switch value.
  • The first matching case wins. Default is used when no case matches. fallback is used when there is no match and no Default.
  • multiple renders every matching case instead of only the first.
  • Case and Default are markers and render nothing when used outside a Switch.

Typed switches with createSwitch

Switch and Case are generic, but TypeScript does not propagate a parent component's type parameters to nested JSX children. Use createSwitch<T>() to bind both components to the same type:

import { createSwitch } from '@jsdevlab/react-headless';

const {
  Switch: StatusSwitch,
  Case: StatusCase,
  Default: StatusDefault,
} = createSwitch<'active' | 'idle' | 'error'>();

<StatusSwitch value={status}>
  <StatusCase value="active">
    <Active />
  </StatusCase>
  <StatusCase value={['idle', 'error']}>
    <Inactive />
  </StatusCase>
  <StatusDefault>
    <Unknown />
  </StatusDefault>
</StatusSwitch>;

Both StatusSwitch value and StatusCase value are checked against 'active' | 'idle' | 'error'.

Await / Catch

import { Await, Catch } from '@jsdevlab/react-headless';

<Await
  promise={userPromise}
  fallback={<Spinner />}
  error={(error, reset) => (
    <ErrorView error={error} onRetry={reset} />
  )}
  onError={(error) => report(error)}
>
  {(user) => <Profile user={user} />}
</Await>;

<Catch
  fallback={(error, reset) => (
    <ErrorView error={error} onRetry={reset} />
  )}
  resetKeys={[userId]}
>
  <Profile />
</Catch>;
  • Await reads a stable promise with React's use API. Pending renders fallback; rejected promises render error when provided, otherwise they propagate to the nearest error boundary.
  • Catch is a headless error boundary. It catches render and lifecycle errors, not errors thrown in event handlers or async code. Changing resetKeys resets the boundary.
  • Both are client components marked with 'use client'.

Portal

import { Portal } from '@jsdevlab/react-headless';

const containerRef = useRef<HTMLDivElement>(null);

<Portal container={containerRef}>
  <Modal />
</Portal>;
  • container accepts an element, a document fragment, a ref object, or null. It defaults to document.body; null renders nothing.
  • disabled renders children inline instead of portaling.
  • Portal renders nothing on the server and portals after mounting on the client. It is a client component marked with 'use client'.

Type safety

  • For infers its item type from each.
  • With narrows away false, null, and undefined.
  • Await infers the resolved promise value.
  • createSwitch<T>() shares one type parameter between Switch and Case.
  • Conditions accept boolean | (() => boolean).
  • Lists and condition arrays are readonly.

Server components

For, Show / When / Unless / Not, With, Repeat / Range, Every / Some / None, and Switch / Case / Default use no hooks or browser APIs and can be used in React Server Components.

Await, Catch, and Portal are client components and are marked with 'use client'.

License

MIT