generateViewport
You can customize the initial viewport of the page with the staticviewport object or the dynamicgenerateViewport function.
Good to know:
- The
viewportobject andgenerateViewportfunction exports areonly supported in Server Components.- You cannot export both the
viewportobject andgenerateViewportfunction from the same route segment.- If you're coming from migrating
metadataexports, you can usemetadata-to-viewport-export codemod to update your changes.
Theviewport object
To define the viewport options, export aviewport object from alayout.jsx orpage.jsx file.
importtype { Viewport }from'next'exportconstviewport:Viewport= { themeColor:'black',}exportdefaultfunctionPage() {}generateViewport function
generateViewport should return aViewport object containing one or more viewport fields.
exportfunctiongenerateViewport({ params }) {return { themeColor:'...', }}In TypeScript, theparams argument can be typed viaPageProps<'/route'> orLayoutProps<'/route'> depending on wheregenerateViewport is defined.
Good to know:
- If the viewport doesn't depend on runtime information, it should be defined using the static
viewportobject rather thangenerateViewport.
Viewport Fields
themeColor
Learn more abouttheme-color.
Simple theme color
importtype { Viewport }from'next'exportconstviewport:Viewport= { themeColor:'black',}<metaname="theme-color"content="black" />With media attribute
importtype { Viewport }from'next'exportconstviewport:Viewport= { themeColor: [ { media:'(prefers-color-scheme: light)', color:'cyan' }, { media:'(prefers-color-scheme: dark)', color:'black' }, ],}<metaname="theme-color"media="(prefers-color-scheme: light)"content="cyan" /><metaname="theme-color"media="(prefers-color-scheme: dark)"content="black" />width,initialScale,maximumScale anduserScalable
Good to know: The
viewportmeta tag is automatically set, and manual configuration is usually unnecessary as the default is sufficient. However, the information is provided for completeness.
importtype { Viewport }from'next'exportconstviewport:Viewport= { width:'device-width', initialScale:1, maximumScale:1, userScalable:false,// Also supported but less commonly used// interactiveWidget: 'resizes-visual',}<metaname="viewport"content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"/>colorScheme
Learn more aboutcolor-scheme.
importtype { Viewport }from'next'exportconstviewport:Viewport= { colorScheme:'dark',}<metaname="color-scheme"content="dark" />Types
You can add type safety to your viewport object by using theViewport type. If you are using thebuilt-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
importtype { Viewport }from'next'exportconstviewport:Viewport= { themeColor:'black',}generateViewport function
Regular function
importtype { Viewport }from'next'exportfunctiongenerateViewport():Viewport {return { themeColor:'black', }}With segment props
importtype { Viewport }from'next'typeProps= { params:Promise<{ id:string }> searchParams:Promise<{ [key:string]:string|string[]|undefined }>}exportfunctiongenerateViewport({ params, searchParams }:Props):Viewport {return { themeColor:'black', }}exportdefaultfunctionPage({ params, searchParams }:Props) {}JavaScript Projects
For JavaScript projects, you can use JSDoc to add type safety.
/**@type{import("next").Viewport} */exportconstviewport= { themeColor:'black',}Version History
| Version | Changes |
|---|---|
v14.0.0 | viewport andgenerateViewport introduced. |
Next Steps
Was this helpful?