> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tanstack/router/llms.txt
> Use this file to discover all available pages before exploring further.

# File Route

# File Route API

File-based routing APIs for creating routes from the filesystem.

## `createFileRoute`

Creates a file-based Route factory for a given path.

```tsx theme={null}
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    return { post }
  },
  component: PostComponent,
})

function PostComponent() {
  const { post } = Route.useLoaderData()
  return <h1>{post.title}</h1>
}
```

### Parameters

<ParamField path="path" type="string" required>
  File path literal for the route (usually auto-generated by the `tsr` generator).
</ParamField>

### Returns

<ResponseField name="createRoute" type="Function">
  A function that accepts Route options and returns a Route instance.

  The returned function accepts all the same options as `createRoute`, including:

  * `loader` - Load data for the route
  * `beforeLoad` - Run before the route loads
  * `component` - The component to render
  * `errorComponent` - Error boundary component
  * `pendingComponent` - Loading component
  * `notFoundComponent` - Not found component
  * `validateSearch` - Validate search params
  * `loaderDeps` - Loader dependencies
  * `staleTime` - Cache staleness time
  * `gcTime` - Garbage collection time
  * And more...
</ResponseField>

## File Route Structure

When using file-based routing, your route files follow a specific naming convention:

### Standard Routes

```
routes/
  index.tsx              → /
  about.tsx              → /about
  posts/
    index.tsx            → /posts
    $postId.tsx          → /posts/$postId
    $postId/
      edit.tsx           → /posts/$postId/edit
```

### Layout Routes

Layout routes don't add a path segment but wrap child routes:

```
routes/
  _layout.tsx            → wraps children without path
  _layout/
    dashboard.tsx        → /dashboard
    settings.tsx         → /settings
```

### Route Groups

Route groups organize routes without affecting the URL:

```
routes/
  (auth)/                → no path segment
    login.tsx            → /login
    register.tsx         → /register
```

## `createLazyFileRoute`

Creates a lazily-configurable file-based route stub by file path for code-splitting.

```tsx theme={null}
// routes/posts.$postId.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts/$postId')({
  component: PostComponent,
})

function PostComponent() {
  const { postId } = Route.useParams()
  return <div>Post {postId}</div>
}
```

### Parameters

<ParamField path="id" type="string" required>
  File path literal for the route file.
</ParamField>

### Returns

<ResponseField name="createLazyRoute" type="Function">
  A function that accepts lazy route options and returns a `LazyRoute`.

  Lazy route options include only non-critical route options:

  * `component` - The component to render
  * `pendingComponent` - Loading component
  * `errorComponent` - Error boundary component
  * `notFoundComponent` - Not found component
</ResponseField>

## Code Splitting Pattern

Split your routes into two files for optimal bundle size:

### Main Route File

```tsx theme={null}
// routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    // Critical data loading
    const post = await fetchPost(params.postId)
    return { post }
  },
  // No component here - it's in the lazy file
})
```

### Lazy File

```tsx theme={null}
// routes/posts.$postId.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts/$postId')({
  component: PostComponent,
})

function PostComponent() {
  const { post } = Route.useLoaderData()
  return <h1>{post.title}</h1>
}
```

## Route File Exports

Route files created with `createFileRoute` can export the following:

### Route Export

```tsx theme={null}
export const Route = createFileRoute('/posts')({
  // Route options
})
```

<ParamField path="Route" type="Route" required>
  The route instance created by `createFileRoute`. This must be the default export or named `Route`.
</ParamField>

## Path Parameters

Define path parameters in your file names:

### Single Parameter

```
routes/posts.$postId.tsx → /posts/:postId
```

### Multiple Parameters

```
routes/posts.$postId.comments.$commentId.tsx → /posts/:postId/comments/:commentId
```

### Splat/Catch-all

```
routes/files.$.tsx → /files/*
```

## Search Parameter Validation

Validate and type search parameters:

```tsx theme={null}
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
import { zodValidator } from '@tanstack/zod-adapter'

const searchSchema = z.object({
  page: z.number().default(1),
  filter: z.enum(['all', 'active', 'completed']).default('all'),
})

export const Route = createFileRoute('/posts')({
  validateSearch: zodValidator(searchSchema),
  loaderDeps: ({ search }) => ({ page: search.page }),
  loader: async ({ deps }) => {
    const posts = await fetchPosts(deps.page)
    return { posts }
  },
})
```

## Route Context

Add context to a route and its children:

```tsx theme={null}
export const Route = createFileRoute('/posts/$postId')({
  beforeLoad: async ({ params, context }) => {
    const post = await fetchPost(params.postId)
    return {
      post,
      getComments: () => fetchComments(params.postId),
    }
  },
})
```

Child routes can access this context:

```tsx theme={null}
// routes/posts.$postId.comments.tsx
export const Route = createFileRoute('/posts/$postId/comments')({
  loader: async ({ context }) => {
    const comments = await context.getComments()
    return { comments }
  },
})
```