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

modal-navigator

v1.1.1

Published

React 19 modal navigator with Promise results, lifecycle events, KeepAlive and precompiled CSS

Readme

Modal Navigator

React 19 modal stack navigation with KeepAlive, Promise results, lifecycle callbacks, focus management, concurrent loading, live theme changes, and precompiled CSS.

Install

npm install @fanya0725/modal-navigator

Import the stylesheet once:

import '@fanya0725/modal-navigator/style.css';

The library's layout and controls do not require Tailwind. Business content can use any styling solution. Tailwind class names passed as backgroundColor are resolved by the host application's Tailwind build; alternatively pass a CSS color such as #ffffff or var(--surface).

Quick start

import { ModalProvider, useModal, useModalLoading, useModalFooter } from '@fanya0725/modal-navigator';
import '@fanya0725/modal-navigator/style.css';

function Home() {
  const { modal } = useModal();
  const choose = async () => {
    const result = await modal.openAsync('users');
    if (result.status === 'confirmed') console.log(result.value);
  };
  return <button onClick={choose}>Choose user</button>;
}

function UserList() {
  const { navigation } = useModal();
  return <button onClick={() => navigation.navigate('UserCreate')}>Create</button>;
}

function UserCreate() {
  const { navigation } = useModal();
  const { showLoading, hideLoading } = useModalLoading();
  const save = async () => {
    const token = showLoading('Saving...');
    try {
      const user = await Promise.resolve({ id: 1, name: 'Ada' });
      hideLoading(token);
      await navigation.close(user); // resolves openAsync({status:'confirmed', value:user})
    } finally { hideLoading(token); }
  };
  useModalFooter({ done: save, doneText: 'Save' });
  return <div>Create user</div>;
}

const registry = {
  users: {
    initialRoute: 'UserList',
    screens: {
      UserList: { title: 'Users', component: UserList },
      UserCreate: { title: 'New user', component: UserCreate },
    },
  },
};

export default function App() {
  return <ModalProvider registry={registry} theme="auto"
    backgroundColor={{ light: '#ffffff', dark: '#334155' }}
    onError={(error, context) => console.error(error, context)}>
    <Home />
  </ModalProvider>;
}

API

  • useModal() returns { modal, navigation } and legacy top-level modal methods (open, close, etc.). navigation methods throw helpful errors only when called outside an active modal screen.
  • modal.open(name, params?, overrides?) opens a modal and returns an internal instance id.
  • modal.openAsync(name, params?, overrides?) returns Promise<ModalResult>: { status: 'confirmed', value, reason }, { status: 'dismissed', reason }, or { status: 'replaced', reason }.
  • navigation.navigate, goBack(result?), replace, reset, close(result?) work inside screens.
  • useModalLoading().showLoading(text?) returns a token. Pass it to hideLoading(token) to avoid prematurely hiding concurrent loading operations. hideLoading() without a token clears the current screen's loading operations for backward compatibility.
  • ModalProvider accepts registry, defaultOptions, theme, backgroundColor, translate, and onError.
  • Modal modalOptions supports onOpen, onBeforeClose, onClose, onNavigate, onRouteChange, onFocus, onBlur.
  • onBeforeClose can be async; returning false cancels closing. Repeated close requests are deduplicated.
  • useModalFooter and useNavigationResult remain supported.

Theme

<ModalProvider registry={registry} theme="auto" backgroundColor={{ light: '#fff', dark: '#334155' }}>
  <App />
</ModalProvider>

Provider theme and background changes update open modals live. Per-modal options override Provider settings. The backgroundColor field also accepts Tailwind class names, but those classes must exist in the consuming app's CSS.

Accessibility

Hidden KeepAlive screens use hidden and inert. Focus is moved to the dialog before a route is hidden, restored when possible, and returned to the opener when the dialog closes. Tab is trapped within the active dialog; Escape is configurable. Background scrolling is locked with scrollbar compensation.

Release

npm install
npm run build
npm pack --dry-run
npm publish --access public

Note: @fanya0725/modal-navigator is the previously published scoped name. Change name in package.json before publishing under a different package name. Never republish an already published version number.

Stability behavior (v1.1.1)

modal.open(name) returns a Promise with the new modal ID, or null when a close guard vetoes replacement. modal.openAsync(name) resolves with {status: 'confirmed', value, reason}, {status: 'dismissed', reason}, or {status: 'replaced', reason}. Replacement runs onBeforeClose and onClose on the old modal. A veto leaves the old modal open and returns a dismissed blocked result to the new openAsync call. Concurrent transitions during a pending guard are blocked.