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-navigatorImport 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.).navigationmethods 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?)returnsPromise<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 tohideLoading(token)to avoid prematurely hiding concurrent loading operations.hideLoading()without a token clears the current screen's loading operations for backward compatibility.ModalProvideracceptsregistry,defaultOptions,theme,backgroundColor,translate, andonError.- Modal
modalOptionssupportsonOpen,onBeforeClose,onClose,onNavigate,onRouteChange,onFocus,onBlur. onBeforeClosecan be async; returningfalsecancels closing. Repeated close requests are deduplicated.useModalFooteranduseNavigationResultremain 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 publicNote: @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.
