Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 72 ยท Routing

Catch-All and Optional Catch-All Routes

Match URLs of any depth with [...slug] and [[...slug]]. See how params become arrays, which route wins when several match, and which layouts are invalid.

A documentation site might have /docs/intro, /docs/guides/install and /docs/guides/advanced/plugins. The depth changes from page to page, and you do not want a folder for every level. A dynamic segment matches exactly one piece of the URL, so it cannot do this job. A catch-all segment can: it matches one piece, two pieces, ten pieces, whatever is left of the URL.

Next.js has two catch-all forms. [...slug] needs at least one piece. [[...slug]] (double brackets) is optional: it also matches the URL with nothing after the prefix. This lesson shows the syntax, how params looks for each, what wins when several routes match, and the mistakes that make a build fail.

Real framework or stand-in? The tsx snippets are real Next.js code and read-only. The live examples are plain JavaScript stand-ins on the code runner. They follow the documented matching rules, and the messages printed by the second stand-in are our own wording, not Next.js's exact error text.

Three brackets, three reaches

[slug] Exactly one segment.
[...slug] One or more segments.
[[...slug]] Zero or more segments.

The more brackets, the more URLs one page file can catch.

1 / 2

[...slug]: one or more segments

Name a folder with three dots inside the brackets and Next.js collects every remaining segment into an array:

TEXT
app/
  docs/
    page.tsx               -> /docs
    [...slug]/
      page.tsx             -> /docs/a, /docs/a/b, /docs/a/b/c ...
URL params
/docs not matched by [...slug] (this is docs/page.tsx)
/docs/intro { slug: ['intro'] }
/docs/guides/install { slug: ['guides', 'install'] }

Even a single segment arrives as an array with one item. That is the difference you notice first: slug is string[], not string. As with every dynamic route in Next.js 15 and 16, params is a promise:

TSX
// app/docs/[...slug]/page.tsx (read-only)
import { notFound } from 'next/navigation';
import { findDoc } from '@/lib/docs';

export default async function DocPage({
  params,
}: {
  params: Promise<{ slug: string[] }>;
}) {
  const { slug } = await params;
  const doc = await findDoc(slug.join('/'));

  if (!doc) {
    notFound();
  }

  return (
    <article>
      <nav aria-label="Breadcrumb">{slug.join(' / ')}</nav>
      <h1>{doc.title}</h1>
    </article>
  );
}

Each item can be percent-encoded, so decode with decodeURIComponent before comparing. And because the route accepts any depth, a typo like /docs/gudies/install also reaches this page. The page must therefore decide for itself whether the path exists and call notFound() when it does not. Without that check, a catch-all quietly turns every mistyped URL into a "200 OK" page, which is bad for visitors and for search engines.

[[...slug]]: zero or more segments

Wrap the same name in two pairs of brackets and the segment becomes optional:

TEXT
app/
  shop/
    [[...filters]]/
      page.tsx             -> /shop, /shop/shoes, /shop/shoes/red
URL params
/shop {} (the filters key is missing, so it reads as undefined)
/shop/shoes { filters: ['shoes'] }
/shop/shoes/red { filters: ['shoes', 'red'] }

The type reflects it: Promise<{ filters?: string[] }>. This form is handy when one component should handle both the landing page and every page below it, for example a product browser that reads its filters from the path, or a CMS where the home page and the inner pages come from the same table. It saves you from writing a page.tsx for the root and a catch-all for the rest.

TSX
// app/shop/[[...filters]]/page.tsx (read-only)
export default async function ShopPage({
  params,
}: {
  params: Promise<{ filters?: string[] }>;
}) {
  const { filters = [] } = await params;
  const [category, color] = filters;

  return (
    <h1>
      {category ? `Shop: ${category}` : 'All products'}
      {color ? ` in ${color}` : ''}
    </h1>
  );
}

For a generated list of pages, generateStaticParams returns arrays for catch-alls: [{ slug: ['guides', 'install'] }, { slug: ['intro'] }].

Which route wins?

More than one route can match a URL. Next.js prefers the most specific one, in this order: static segments, then dynamic [x], then catch-all [...x], then optional catch-all [[...x]]. The comparison is made segment by segment from the left. In practice:

  • app/docs/getting-started/page.tsx beats app/docs/[...slug]/page.tsx for /docs/getting-started.
  • app/docs/[section]/page.tsx beats the catch-all for /docs/guides (one segment), but not for /docs/guides/install, which has two segments, so only the catch-all fits.
  • Because the catch-all is the least specific, you can safely add static pages next to it later and they will take over their URLs without touching the catch-all.

The first live example implements those priorities. It builds a pattern from every file name, finds all patterns that fit the URL and picks the most specific. Notice how /docs is answered by docs/page.tsx and not by [...slug], and how /shop is answered by the optional catch-all with no filters key at all.

Node.js Catch-all matching with priorities

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The stand-in shows the whole rule in about forty lines: score each segment, compare from the left, prefer the lower score. Real Next.js builds a route table at build time, but the behavior you observe from the outside is the same.

Layouts that Next.js rejects

A catch-all has to stay in its place, and a few combinations are errors. These are the ones you are most likely to meet:

  1. A catch-all must be the last segment. app/docs/[...slug]/edit/page.tsx cannot work, because the catch-all would have to swallow the rest of the URL and leave edit for the folder below it. Use a query parameter or a separate route instead.
  2. An optional catch-all cannot sit beside a page at the same path. If app/shop/[[...filters]]/page.tsx already answers /shop, an extra app/shop/page.tsx competes for the same URL. Keep one of them.
  3. Names must agree in one position. app/docs/[...slug] and app/docs/[...path] would be two different names for the same slot.

These errors appear at build or dev-server start, so they are easy to catch. Here is a tiny linter that reports the three conflicts above for a list of files. The messages are our own wording; the real ones are worded differently, but the rules are the same.

Node.js A route linter for catch-all conflicts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Catch-all or something else?

Catch-alls are powerful, which is why it pays to reach for them last:

  • If the depth is fixed (/shop/shoes/42), use nested dynamic segments. Each level then has a name, and generateStaticParams can use the parent's value.
  • If the filter values are optional and unordered (?color=red&size=m), the URL is better served by search params than by path segments.
  • If you only want a friendlier 404 page, you do not need a catch-all: add app/not-found.tsx and use not-found handling.
  • If your content tree comes from files or a CMS (docs, wikis, file browsers), a catch-all is exactly right. Keep the lookup in one function and always handle "not found".

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does params contain for /docs/guides/install when the page is app/docs/[...slug]/page.tsx?

    A catch-all segment collects every remaining segment into an array, so you get one item per URL segment.
  2. 2. Which URL is matched by [[...slug]] but NOT by [...slug] (both placed under /shop)?

    The optional form also accepts zero remaining segments. [...slug] needs at least one, so /shop alone would need its own page.
  3. 3. app/docs/getting-started/page.tsx and app/docs/[...slug]/page.tsx both exist. Which handles /docs/getting-started?

    Static segments win over dynamic ones, and dynamic ones win over catch-alls. That lets you add special pages without touching the catch-all.
  4. 4. Why should a catch-all page call notFound() for unknown paths?

    A catch-all swallows every URL below its prefix, including typos. Only your own lookup knows whether the content exists.
  5. 5. Which folder layout is invalid?

    A catch-all must be the last segment of a route, because it consumes everything after it. A page cannot live in a folder beneath it.

Summary

  • [...slug] matches one or more segments and gives params.slug as a string[]; [[...slug]] also matches zero segments, and then slug is missing (undefined).
  • params is a promise in Next.js 15 and 16, and every item in the array can be percent-encoded.
  • Priority runs from most to least specific: static, dynamic, catch-all, optional catch-all.
  • A catch-all has to be the last segment, an optional catch-all cannot share its URL with a plain page.tsx, and names must agree per position.
  • Always check that the content exists and call notFound() otherwise, because a catch-all would match typos too.
  • Prefer fixed nested segments or search params when the shape of the URL is known.

Next: Route Groups and Private Folders