react-terminal-404

Drop-in terminal-style 404 page for React. Virtual filesystem, fake apt install, kernel-panic destruct animation. Zero config.

→ Try the live demo

Why

Most 404 pages are a dead end. This one lets the user poke around — ls, cd, mkdir, cat, apt install, the works — while they figure out where they meant to go. Drop it in your router's catch-all and forget about it.

Install

npm install react-terminal-404

Peer deps: react >= 17, react-dom >= 17. Works with Next.js App Router ("use client" is preserved in the build).

Usage

import { Terminal404 } from 'react-terminal-404';

export default function NotFoundPage() {
  return <Terminal404 />;
}

That's it. No CSS imports, no setup. The component reads window.location.pathname to show what was missing, and clicking home → (or typing home / exit) navigates to /.

React Router

import { createBrowserRouter } from 'react-router-dom';
import { Terminal404 } from 'react-terminal-404';

const router = createBrowserRouter([
  // …your routes…
  { path: '*', element: <Terminal404 /> },
]);

Next.js (App Router)

// app/not-found.tsx
import { Terminal404 } from 'react-terminal-404';

export default function NotFound() {
  return <Terminal404 />;
}

Custom navigation

If you want to use your router's navigation instead of window.location.assign:

import { useNavigate } from 'react-router-dom';
import { Terminal404 } from 'react-terminal-404';

export default function NotFoundPage() {
  const navigate = useNavigate();
  return <Terminal404 onNavigateHome={() => navigate('/')} />;
}

What works in the terminal

| Command | Behavior | |---|---| | help, ? | List commands | | ls, cd, pwd, mkdir, touch, cat, rm [-rf] | Real virtual filesystem | | echo foo > file, echo foo >> file | Write / append | | clear (or Ctrl+L) | Wipe screen | | history, whoami, date | Basics | | apt install <pkg>, npm install, yarn add | Fake progress bar | | sudo <anything> | "you are already root. behave." | | sudo rm -rf / | Full kernel-panic destruct sequence | | vim, nano, emacs | Editor war jokes | | git commit/push/status | Dry humor | | make coffee | 418 | | fortune, cowsay <msg> | Classics | | home, exit, quit | Navigate back |

UX details: ↑/↓ arrows scroll command history. Ctrl+C cancels current line. Click anywhere to refocus the input.

Props

interface Terminal404Props {
  /** Path that "doesn't exist" — shown as the boot `cd …` failure. Defaults to window.location.pathname. */
  pathname?: string;
  /** Prompt user/host. Defaults to root@localhost. */
  prompt?: { user?: string; host?: string };
  /** Called when the user types `home` / `exit` or clicks the home button. Defaults to `window.location.assign('/')`. */
  onNavigateHome?: () => void;
  /** Show the top-right home button. Default true. */
  homeButton?: boolean;
  /** Override the boot banner shown above the failed `cd`. */
  bootMessage?: string;
  /** Enable the kernel-panic destruct sequence on `rm -rf /`. Default true. */
  heartAttack?: boolean;
  /** Optional className applied to the outer wrapper. */
  className?: string;
}

Examples

// Branded prompt
<Terminal404 prompt={{ user: 'you', host: 'acme.dev' }} />

// Custom boot banner
<Terminal404 bootMessage="acme.dev terminal · build 42 (it's all fine)" />

// Disable the destruct animation (some users do not enjoy a 2.5-second blackout)
<Terminal404 heartAttack={false} />

// Hide the home button (e.g., if your layout has its own escape hatch)
<Terminal404 homeButton={false} />

What this is not

• Not a real terminal emulator. Use @xterm/xterm for that.
• Not a generic terminal-emulator React component. Use react-console-emulator if you want to wire your own commands from scratch.
• Not customizable beyond the props above (yet). Custom user-defined commands are planned for 0.2.

This package is opinionated about being a 404 page. The commands, jokes, and animations are batteries-included.

Versioning

0.x while the API is in flux. After 1.0, semver as usual.

License

MIT © Amimul Ehshan