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 andgenerateViewport
function exports are only supported in Server Components.- You cannot export both the
viewport
object andgenerateViewport
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.js
or page.js
file.
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.
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 thangenerateMetadata
.
Viewport Fields
themeColor
Learn more about theme-color.
Simple theme color
export const viewport = {
themeColor: 'black',
}
<meta name="theme-color" content="black" />
With media attribute
export const 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
, 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.
export const viewport = {
width: 'device-width',
initialScale: 1,
maximumScale: 1,
// Also supported by less commonly used
// interactiveWidget: 'resizes-visual',
}
<meta
name="viewport"
content="width=device-width, initial-scale=1, maximum-scale=1"
/>
colorScheme
Learn more about color-scheme
.
export const 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: { 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
Version | Changes |
---|---|
v14.0.0 | viewport and generateViewport introduced. |
Next Steps
Was this helpful?