Dynamic route viewport settings
A route's theme color or color scheme depends on route-specific data.
Next.js 16+ · Function
generateViewport
generateViewport dynamically defines a route's initial viewport configuration in a Next.js App Router page or layout. Return a Viewport object; use the static viewport export for settings that do not need dynamic computation.
- Since
- Next.js 14
How it works
Export generateViewport from a layout or page when viewport settings must be computed dynamically. It returns a Viewport object; use the static viewport export instead when the values do not depend on dynamic data.
Syntax
export function generateViewport({ params }): Viewport { return { ... } }Parameters
| Name | Type | Description |
|---|---|---|
params | object | The route parameters supplied to the page or layout; available when the viewport depends on dynamic route data. |
Returns
A Viewport object containing one or more viewport fields.
Key points
- Use generateViewport for computed viewport settings, or export viewport for fixed settings.
- The function returns a Viewport object containing fields such as themeColor, colorScheme, width, or initialScale.
- The API is available from route-segment page and layout files.
- Type the params argument with the route-specific PageProps or LayoutProps helper when needed.
Common mistakes
- Export it from a Server Component; it cannot be defined in a Client Component.
- Choose either the static viewport object or generateViewport in one page or layout.
- Do not use a dynamic function when a fixed viewport configuration is sufficient.
- Viewport output must be available for the initial load and cannot be deferred like streamable metadata.
Example: Dynamic viewport configuration
import type { Viewport } from 'next'
export function generateViewport(): Viewport {
return {
themeColor: 'black',
colorScheme: 'dark',
width: 'device-width',
initialScale: 1,
}
}
export default function Layout({
children,
}: Readonly<{ children: React.ReactNode }>) {
return <html lang="en"><body>{children}</body></html>
}This server-component layout computes the initial viewport configuration and returns it as a typed Viewport object.
When to use it
Data-driven viewport configuration
A layout needs to compute viewport fields from external data.
Type-safe viewport output
The application needs a typed viewport declaration in TypeScript.
Related
viewportViewportPagePropsLayoutPropsthemeColorcolorScheme