Next.js Documentation (Official Mirror)

You can customize the initial viewport of the page with the static viewport object or the dynamic generateViewport function.

Good to know: - The viewport object and generateViewport function exports are only supported in Server Components. - You cannot export both the viewport object and generateViewport function from the same route segment. - If you're coming from migrating metadata exports, you can use metadata-to-viewport-export codemod to update your changes.

The `viewport` object

To define the viewport options, export a viewport object from a layout.jsx or page.jsx file.

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  themeColor: 'black',
}

export default function Page() {}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  themeColor: 'black',
}

export default function Page() {}

`generateViewport` function

generateViewport should return a Viewport object containing one or more viewport fields.

tsx

filename="layout.tsx | page.tsx" switcher
export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

In TypeScript, the params argument can be typed via PageProps<'/route'> or LayoutProps<'/route'> depending on where generateViewport is defined.

jsx

filename="layout.js | page.js" switcher
export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

Good to know: - If the viewport doesn't depend on request information, it should be defined using the static viewport object rather than generateViewport.

Viewport Fields

`themeColor`

Learn more about theme-color.

Simple theme color

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  themeColor: 'black',
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  themeColor: 'black',
}

html

filename="<head> output" hideLineNumbers
<meta name="theme-color" content="black" />

With media attribute

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}

html

filename="<head> output" hideLineNumbers
<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" />

`width`, `initialScale`, `maximumScale` and `userScalable`

Good to know: The viewport meta tag is automatically set, and manual configuration is usually unnecessary as the default is sufficient. However, the information is provided for completeness.

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

html

filename="<head> output" hideLineNumbers
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>

`colorScheme`

Learn more about color-scheme.

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  colorScheme: 'dark',
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  colorScheme: 'dark',
}

html

filename="<head> output" hideLineNumbers
<meta name="color-scheme" content="dark" />

With Cache Components

When Cache Components is enabled, generateViewport follows the same rules as other components. If viewport accesses runtime data (cookies(), headers(), params, searchParams) or performs uncached data fetching, it defers to request time.

Unlike metadata, viewport cannot be streamed because it affects initial page load UI. If generateViewport defers to request time, the page would need to block until resolved.

If viewport depends on external data but not runtime data, use use cache:

tsx

filename="app/layout.tsx" highlight={2}
export async function generateViewport() {
  'use cache'
  const { width, initialScale } = await db.query('viewport-size')
  return { width, initialScale }
}

If viewport genuinely requires runtime data, wrap the document <body> in a Suspense boundary to signal that the entire route should be dynamic:

tsx

filename="app/layout.tsx" highlight={1,13,17}

export async function generateViewport() {
  const cookieJar = await cookies()
  return {
    themeColor: cookieJar.get('theme-color')?.value,
  }
}

export default function RootLayout({ children }) {
  return (
    <Suspense>
      <html>
        <body>{children}</body>
      </html>
    </Suspense>
  )
}

Caching is preferred because it allows static shell generation. Wrapping the document body in Suspense means there is no static shell or content to immediately send when a request arrives, making the entire route block until ready on every request.

Good to know: Use multiple root layouts to isolate fully dynamic viewport to specific routes, while still letting other routes in your application generate a static shell.

Types

You can add type safety to your viewport object by using the Viewport type. If you are using the built-in TypeScript plugin in your IDE, you do not need to manually add the type, but you can still explicitly add it if you want.

`viewport` object

tsx


export const viewport: Viewport = {
  themeColor: 'black',
}

`generateViewport` function

Regular function

tsx


export function generateViewport(): Viewport {
  return {
    themeColor: 'black',
  }
}

With segment props

tsx


type Props = {
  params: Promise<{ id: string }>
  searchParams: Promise<{  | string[] | undefined }>
}

export function generateViewport({ params, searchParams }: Props): Viewport {
  return {
    themeColor: 'black',
  }
}

export default function Page({ params, searchParams }: Props) {}

JavaScript Projects

For JavaScript projects, you can use JSDoc to add type safety.

/** @type {import("next").Viewport} */
export const viewport = {
  themeColor: 'black',
}

Version History

Version	Changes
`v14.0.0`	`viewport` and `generateViewport` introduced.

You can customize the initial viewport of the page with the static viewport object or the dynamic generateViewport function.

Good to know: - The viewport object and generateViewport function exports are only supported in Server Components. - You cannot export both the viewport object and generateViewport function from the same route segment. - If you're coming from migrating metadata exports, you can use metadata-to-viewport-export codemod to update your changes.

The `viewport` object

To define the viewport options, export a viewport object from a layout.jsx or page.jsx file.

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  themeColor: 'black',
}

export default function Page() {}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  themeColor: 'black',
}

export default function Page() {}

`generateViewport` function

generateViewport should return a Viewport object containing one or more viewport fields.

tsx

filename="layout.tsx | page.tsx" switcher
export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

In TypeScript, the params argument can be typed via PageProps<'/route'> or LayoutProps<'/route'> depending on where generateViewport is defined.

jsx

filename="layout.js | page.js" switcher
export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

Good to know: - If the viewport doesn't depend on request information, it should be defined using the static viewport object rather than generateViewport.

Viewport Fields

`themeColor`

Learn more about theme-color.

Simple theme color

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  themeColor: 'black',
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  themeColor: 'black',
}

html

filename="<head> output" hideLineNumbers
<meta name="theme-color" content="black" />

With media attribute

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}

html

filename="<head> output" hideLineNumbers
<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" />

`width`, `initialScale`, `maximumScale` and `userScalable`

Good to know: The viewport meta tag is automatically set, and manual configuration is usually unnecessary as the default is sufficient. However, the information is provided for completeness.

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

html

filename="<head> output" hideLineNumbers
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>

`colorScheme`

Learn more about color-scheme.

tsx

filename="layout.tsx | page.tsx" switcher

export const viewport: Viewport = {
  colorScheme: 'dark',
}

jsx

filename="layout.jsx | page.jsx" switcher
export const viewport = {
  colorScheme: 'dark',
}

html

filename="<head> output" hideLineNumbers
<meta name="color-scheme" content="dark" />

With Cache Components

Unlike metadata, viewport cannot be streamed because it affects initial page load UI. If generateViewport defers to request time, the page would need to block until resolved.

If viewport depends on external data but not runtime data, use use cache:

tsx

filename="app/layout.tsx" highlight={2}
export async function generateViewport() {
  'use cache'
  const { width, initialScale } = await db.query('viewport-size')
  return { width, initialScale }
}

If viewport genuinely requires runtime data, wrap the document <body> in a Suspense boundary to signal that the entire route should be dynamic:

tsx

filename="app/layout.tsx" highlight={1,13,17}

export async function generateViewport() {
  const cookieJar = await cookies()
  return {
    themeColor: cookieJar.get('theme-color')?.value,
  }
}

export default function RootLayout({ children }) {
  return (
    <Suspense>
      <html>
        <body>{children}</body>
      </html>
    </Suspense>
  )
}

Good to know: Use multiple root layouts to isolate fully dynamic viewport to specific routes, while still letting other routes in your application generate a static shell.

Types

`viewport` object

tsx


export const viewport: Viewport = {
  themeColor: 'black',
}

`generateViewport` function

Regular function

tsx


export function generateViewport(): Viewport {
  return {
    themeColor: 'black',
  }
}

With segment props

tsx


type Props = {
  params: Promise<{ id: string }>
  searchParams: Promise<{  | string[] | undefined }>
}

export function generateViewport({ params, searchParams }: Props): Viewport {
  return {
    themeColor: 'black',
  }
}

export default function Page({ params, searchParams }: Props) {}

JavaScript Projects

For JavaScript projects, you can use JSDoc to add type safety.

/** @type {import("next").Viewport} */
export const viewport = {
  themeColor: 'black',
}

Version History

Version	Changes
`v14.0.0`	`viewport` and `generateViewport` introduced.

The viewport object

generateViewport function

Viewport Fields

themeColor

width, initialScale, maximumScale and userScalable

colorScheme

With Cache Components

Types

viewport object

generateViewport function

Regular function

With segment props

JavaScript Projects

Version History

The viewport object

generateViewport function

Viewport Fields

themeColor

width, initialScale, maximumScale and userScalable

colorScheme

With Cache Components

Types

viewport object

generateViewport function

Regular function

With segment props

JavaScript Projects

Version History

The `viewport` object

`generateViewport` function

`themeColor`

`width`, `initialScale`, `maximumScale` and `userScalable`

`colorScheme`

`viewport` object

`generateViewport` function

The `viewport` object

`generateViewport` function

`themeColor`

`width`, `initialScale`, `maximumScale` and `userScalable`

`colorScheme`

`viewport` object

`generateViewport` function