DocumentationShowcaseBlog

generateViewport

API Reference for the generateViewport function.

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.

import type { 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.

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.

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 generateViewport.

Viewport Fields

themeColor

Learn more about theme-color.

Simple theme color

import type { Viewport } from 'next'
 
export const viewport: Viewport = {
  themeColor: 'black',
}
<head> output
<meta name="theme-color" content="black" />

With media attribute

import type { Viewport } from 'next'
 
export const viewport: 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, 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.

import type { Viewport } from 'next'
 
export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}
<head> output
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>

colorScheme

Learn more about color-scheme.

import type { Viewport } from 'next'
 
export const viewport: 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: Promise<{ id: string }>
  searchParams: Promise<{ [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.

On this page