Skip to content
App Router...FunctionsgenerateViewport

generateViewport

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.

The viewport object

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

layout.tsx | page.tsx
import { Viewport } from 'next'
 
export const viewport: Viewport = {
  themeColor: 'black',
}
 
export default function Page() {}

generateViewport function

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

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

Good to know:

  • If the viewport doesn't depend on runtime information, it should be defined using the static viewport object rather than generateMetadata.
  • Marking generateViewport as async is not yet supported. If you still require this functionality, continue using the previous generateMetadata option. We will be adding support for async in an upcoming minor release.

Viewport Fields

themeColor

Learn more about theme-color.

Simple theme color

layout.js | page.js
export const viewport = {
  themeColor: 'black',
}
<head> output
<meta name="theme-color" content="black" />

With media attribute

layout.js | page.js
export const viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}
<head> output
<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" />

width, initialScale, and maximumScale

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

layout.js | page.js
export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  // Also supported by less commonly used
  // interactiveWidget: 'resizes-visual',
}
<head> output
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1"
/>

colorScheme

Learn more about color-scheme.

layout.js | page.js
export const viewport = {
  colorScheme: 'dark',
}
<head> output
<meta name="color-scheme" content="dark" />

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

import type { Viewport } from 'next'
 
export const viewport: Viewport = {
  themeColor: 'black',
}

generateViewport function

Regular function

import type { Viewport } from 'next'
 
export function generateViewport(): Viewport {
  return {
    themeColor: 'black',
  }
}

With segment props

import type { Viewport } from 'next'
 
type Props = {
  params: { id: string }
  searchParams: { [key: string]: string | 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

VersionChanges
v14.0.0viewport and generateViewport introduced.