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.
• 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: '...',  } }

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', }

<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' },  ], }

<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', }

<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', }

<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