DocsPluginsShowcaseReleases
npmStar us on GitHub

Getting Started

IntroductionInstallationProject StructureLayouts and PagesLinking and Navigating

Routing

Folder-Based RoutingFile-Based RoutingDynamic RoutesParallel RoutesIntercepting RoutesCatch-All RoutesMDX & Markdown Pages

Special Files

Loading UIError BoundariesTemplateDefaultNot Found

Data Fetching

LoadersActionsAccessing Route Data

Metadata

Metadata & SEOOpen Graph & TwitterIcons & Favicons

API Routes

API Routes OverviewPlain Function HandlersHono IntegrationDynamic API Routes

Environment Variables

OverviewPrefixes & Client ExposureUsing in API Routes

Styling

CSS OverviewTailwind CSSCSS Modules

Platforms

WebWindowsmacOSLinuxAndroidiOS

Deployment

Deployment OverviewProduction ServerStatic ExportHosting Providers

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

Not Found (404)

Custom 404 UI with not-found.tsx - special file, no URL, nearest-wins.

Overview

Bini.js ships a built-in 404. Add not-found.tsx in any folder for custom UI when no route matches. It is a special file - it does not create a URL. Nearest-wins applies.

FilePurpose
src/app/page.tsxHome page
src/app/not-found.tsxGlobal 404 fallback
src/app/blog/not-found.tsxBlog-specific 404

Global 404 Page

Create not-found.tsx at the root of app/ to handle all unmatched routes.

app
layout.tsx
page.tsx
not-found.tsx
/
src/app/not-found.tsx
import { Link } from 'react-router-dom'

export default function NotFound() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1 className="text-4xl font-bold">404</h1>
      <p className="mb-6">The page you&apos;re looking for doesn&apos;t exist.</p>
      <Link to="/">Return Home</Link>
    </div>
  )
}
Shown for unmatched paths like /non-existent or /blog/invalid-post when no closer not-found exists.

Nested 404 Pages

Place not-found.tsx in subdirectories for segment-specific 404 UI. The closest file to the unmatched path wins.

app
not-found.tsx
blog
not-found.tsx
page.tsx
[slug]
page.tsx
admin
not-found.tsx
page.tsx
/blog
/blog/:slug
/admin
src/app/blog/not-found.tsx
import { Link } from 'react-router-dom'

export default function BlogNotFound() {
  return (
    <div className="py-12 text-center">
      <h1 className="text-3xl font-bold">Post Not Found</h1>
      <p className="mb-6">The blog post you&apos;re looking for doesn&apos;t exist.</p>
      <Link to="/blog">View all posts</Link>
    </div>
  )
}
URL404 Page Used
/blog/non-existentsrc/app/blog/not-found.tsx
/admin/invalidsrc/app/admin/not-found.tsx
/completely/wrongsrc/app/not-found.tsx (global)

Programmatic 404

When a route matches but data is missing, return your own not-found UI from the page component.

src/app/blog/[slug]/page.tsx
import { useParams, Link } from 'react-router-dom'

export default function BlogPost() {
  const { slug } = useParams<{ slug: string }>()
  const post = getPost(slug)

  if (!post) {
    return (
      <div className="py-12 text-center">
        <h1>Post Not Found</h1>
        <p>The post &quot;{slug}&quot; doesn&apos;t exist.</p>
        <Link to="/blog">View all posts</Link>
      </div>
    )
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

404 with Layout

not-found.tsx is rendered inside the layout chain of the segment it belongs to. Headers and sidebars stay visible.

app
layout.tsx
not-found.tsx
blog
layout.tsx
not-found.tsx
page.tsx
/blog
src/app/blog/layout.tsx
import { Outlet } from 'react-router-dom'

export default function BlogLayout() {
  return (
    <div>
      <header className="mb-8">
        <h1 className="text-2xl font-bold">Blog</h1>
      </header>
      <main><Outlet /></main>
    </div>
  )
}
blog/not-found still shows the Blog header from blog/layout.

Styling 404 Pages

Build any UI you want - copy, links, and actions are all client-side.

src/app/not-found.tsx
import { Link } from 'react-router-dom'

export default function NotFound() {
  return (
    <div className="flex min-h-[60vh] flex-col items-center justify-center px-4 text-center">
      <h1 className="text-9xl font-bold">404</h1>
      <h2 className="mb-3 text-3xl font-bold">Page Not Found</h2>
      <p className="mb-8 max-w-md text-neutral-500">
        The page you&apos;re looking for might have been removed or doesn&apos;t exist.
      </p>
      <div className="flex gap-4">
        <Link
          to="/"
          className="rounded-lg bg-black px-6 py-3 text-white dark:bg-white dark:text-black"
        >
          Go Home
        </Link>
        <button
          onClick={() => window.history.back()}
          className="rounded-lg border px-6 py-3"
        >
          Go Back
        </button>
      </div>
    </div>
  )
}

Complete Example

app
layout.tsx
page.tsx
not-found.tsx
blog
layout.tsx
not-found.tsx
page.tsx
[slug]
page.tsx
dashboard
layout.tsx
not-found.tsx
page.tsx
settings
page.tsx
/
/blog
/blog/:slug
/dashboard
/dashboard/settings
FilePurpose
src/app/page.tsxHome page
src/app/not-found.tsxGlobal 404
src/app/blog/not-found.tsxBlog 404
src/app/dashboard/not-found.tsxDashboard 404

Default

Fallback for a parallel route slot with no match.

Metadata & SEO

Control titles, descriptions, and social previews per route.

Error Boundaries

Catch render errors and show a fallback UI.

Template

Wrap each page individually inside the layout chain.

Layouts and Pages

Create your first pages and wrap them in shared layouts.

Folder-Based Routing

Define routes with folders and page files inside them.

Was this helpful?
PreviousDefault
NextLoaders

On this page

  • Overview
  • Global 404 Page
  • Nested 404 Pages
  • Programmatic 404
  • 404 with Layout
  • Styling 404 Pages
  • Complete Example
Edit this page on GitHub

Not Found (404)

Custom 404 UI with not-found.tsx - special file, no URL, nearest-wins.

Overview

Bini.js ships a built-in 404. Add not-found.tsx in any folder for custom UI when no route matches. It is a special file - it does not create a URL. Nearest-wins applies.

FilePurpose
src/app/page.tsxHome page
src/app/not-found.tsxGlobal 404 fallback
src/app/blog/not-found.tsxBlog-specific 404

Global 404 Page

Create not-found.tsx at the root of app/ to handle all unmatched routes.

app
layout.tsx
page.tsx
not-found.tsx
/
src/app/not-found.tsx
import { Link } from 'react-router-dom'

export default function NotFound() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1 className="text-4xl font-bold">404</h1>
      <p className="mb-6">The page you&apos;re looking for doesn&apos;t exist.</p>
      <Link to="/">Return Home</Link>
    </div>
  )
}
Shown for unmatched paths like /non-existent or /blog/invalid-post when no closer not-found exists.

Nested 404 Pages

Place not-found.tsx in subdirectories for segment-specific 404 UI. The closest file to the unmatched path wins.

app
not-found.tsx
blog
not-found.tsx
page.tsx
[slug]
page.tsx
admin
not-found.tsx
page.tsx
/blog
/blog/:slug
/admin
src/app/blog/not-found.tsx
import { Link } from 'react-router-dom'

export default function BlogNotFound() {
  return (
    <div className="py-12 text-center">
      <h1 className="text-3xl font-bold">Post Not Found</h1>
      <p className="mb-6">The blog post you&apos;re looking for doesn&apos;t exist.</p>
      <Link to="/blog">View all posts</Link>
    </div>
  )
}
URL404 Page Used
/blog/non-existentsrc/app/blog/not-found.tsx
/admin/invalidsrc/app/admin/not-found.tsx
/completely/wrongsrc/app/not-found.tsx (global)

Programmatic 404

When a route matches but data is missing, return your own not-found UI from the page component.

src/app/blog/[slug]/page.tsx
import { useParams, Link } from 'react-router-dom'

export default function BlogPost() {
  const { slug } = useParams<{ slug: string }>()
  const post = getPost(slug)

  if (!post) {
    return (
      <div className="py-12 text-center">
        <h1>Post Not Found</h1>
        <p>The post &quot;{slug}&quot; doesn&apos;t exist.</p>
        <Link to="/blog">View all posts</Link>
      </div>
    )
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

404 with Layout

not-found.tsx is rendered inside the layout chain of the segment it belongs to. Headers and sidebars stay visible.

app
layout.tsx
not-found.tsx
blog
layout.tsx
not-found.tsx
page.tsx
/blog
src/app/blog/layout.tsx
import { Outlet } from 'react-router-dom'

export default function BlogLayout() {
  return (
    <div>
      <header className="mb-8">
        <h1 className="text-2xl font-bold">Blog</h1>
      </header>
      <main><Outlet /></main>
    </div>
  )
}
blog/not-found still shows the Blog header from blog/layout.

Styling 404 Pages

Build any UI you want - copy, links, and actions are all client-side.

src/app/not-found.tsx
import { Link } from 'react-router-dom'

export default function NotFound() {
  return (
    <div className="flex min-h-[60vh] flex-col items-center justify-center px-4 text-center">
      <h1 className="text-9xl font-bold">404</h1>
      <h2 className="mb-3 text-3xl font-bold">Page Not Found</h2>
      <p className="mb-8 max-w-md text-neutral-500">
        The page you&apos;re looking for might have been removed or doesn&apos;t exist.
      </p>
      <div className="flex gap-4">
        <Link
          to="/"
          className="rounded-lg bg-black px-6 py-3 text-white dark:bg-white dark:text-black"
        >
          Go Home
        </Link>
        <button
          onClick={() => window.history.back()}
          className="rounded-lg border px-6 py-3"
        >
          Go Back
        </button>
      </div>
    </div>
  )
}

Complete Example

app
layout.tsx
page.tsx
not-found.tsx
blog
layout.tsx
not-found.tsx
page.tsx
[slug]
page.tsx
dashboard
layout.tsx
not-found.tsx
page.tsx
settings
page.tsx
/
/blog
/blog/:slug
/dashboard
/dashboard/settings
FilePurpose
src/app/page.tsxHome page
src/app/not-found.tsxGlobal 404
src/app/blog/not-found.tsxBlog 404
src/app/dashboard/not-found.tsxDashboard 404

Default

Fallback for a parallel route slot with no match.

Metadata & SEO

Control titles, descriptions, and social previews per route.

Error Boundaries

Catch render errors and show a fallback UI.

Template

Wrap each page individually inside the layout chain.

Layouts and Pages

Create your first pages and wrap them in shared layouts.

Folder-Based Routing

Define routes with folders and page files inside them.

Was this helpful?
PreviousDefault
NextLoaders

On this page

  • Overview
  • Global 404 Page
  • Nested 404 Pages
  • Programmatic 404
  • 404 with Layout
  • Styling 404 Pages
  • Complete Example
Edit this page on GitHub