---
title: Layouts
sort: 150
section-id: core-concepts
keywords: layouts, nested layouts, shared layouts, layout groups, _layout, slots
description: How to use nested layouts, shared layouts, and layout groups in Velox
language: en
---
# Layouts
Layouts define the structural shell around your page content — navigation headers, sidebars, footers, and anything else that persists across multiple pages. Velox provides a flexible, composable layout system built directly into the file-based router.
## Default Layout
The file `layouts/default.velox` is the root layout applied to all routes unless overridden:
```tsx
// layouts/default.velox
---
import Header from '../components/Header.tsx';
import Footer from '../components/Footer.tsx';
---
{meta.title} — My App
```
The `` element is where the current page's content is injected. Layout files receive `meta` (the exports from the route's server block) and `params` automatically.
## Route-Level Layout Override
A route can specify a different layout using the `layout` export in its server block:
```tsx
---
export const layout = 'minimal'; // uses layouts/minimal.velox
export const meta = { title: 'Login' };
---
```
Set `layout` to `false` to render the page with no layout at all:
```tsx
---
export const layout = false; // bare HTML response
---
...
```
## `_layout.velox` — Directory Scoped Layouts
Place a `_layout.velox` file inside any `routes/` subdirectory to apply a layout to all routes in that directory and its subdirectories:
```
routes/
├── _layout.velox ← root layout (all routes)
├── index.velox
├── about.velox
└── admin/
├── _layout.velox ← admin layout (only /admin/* routes)
├── index.velox
└── users/
├── _layout.velox ← users layout (only /admin/users/* routes)
└── index.velox
```
Layouts nest — the admin layout wraps its content inside the root layout's ``, and the users layout wraps inside the admin layout's ``:
```
Root Layout
└── Admin Layout
└── Users Layout
└── Page Content
```
### Admin Layout Example
```tsx
// routes/admin/_layout.velox
---
import AdminNav from '../../components/AdminNav.tsx';
const user = request.context.get('user');
export const meta = { title: 'Admin' };
---
```
## Layout Groups
Wrap a directory in parentheses to create a **route group** that applies a shared layout without affecting the URL:
```
routes/
├── (public)/
│ ├── _layout.velox ← marketing/public layout
│ ├── index.velox → /
│ └── pricing.velox → /pricing
└── (app)/
├── _layout.velox ← application layout (requires auth)
├── dashboard.velox → /dashboard
└── settings.velox → /settings
```
Both `/` and `/pricing` use the public layout. Both `/dashboard` and `/settings` use the app layout. The group name `(public)` and `(app)` never appear in the URL.
## Shared Layout Components
For UI elements shared between multiple layouts (a navigation bar used by both the public and admin layouts, for example), extract them as regular components:
```tsx
// components/TopNav.tsx
interface TopNavProps {
links: { label: string; href: string }[];
user?: User | null;
}
export default function TopNav({ links, user }: TopNavProps) {
return (
);
}
```
Use it in both layouts:
```tsx
// layouts/default.velox
// routes/admin/_layout.velox
```
## Data in Layouts
`_layout.velox` files have their own server block and can fetch data independently:
```tsx
// routes/dashboard/_layout.velox
---
import { db } from '$lib/db';
const user = request.context.get('user');
const notifications = await db.notifications.findUnread(user.id);
---
```
Layout data is fetched in parallel with page data — there is no waterfall.
## Parallel Slots
For complex layouts with multiple content regions, use named parallel slots:
```tsx
// A layout that accepts both main content and a sidebar
---
export const slots = ['default', 'sidebar'];
---
```
Fill the named slot from the page:
```tsx
---
export const layout = 'two-column';
---
Main content here
```
## `` Management
Layouts and pages can both add content to the HTML `` using the `` component:
```tsx
import { Head } from 'velox';
```
`` insertions from nested layouts and pages are all collected and deduplicated before the final HTML is emitted.