How to Lock Screen Orientation in Your Progressive Web App (PWA) Using manifest.json
Written by: Davaadulam | Software Engineer
What is PWA?
A progressive web app (PWA) is an app that's built using web platform technologies, but that provides a user experience like that of a platform-specific app.
Like a website, a PWA can run on multiple platforms and devices from a single codebase. Like a platform-specific app, it can be installed on the device, can operate while offline and in the background, and can integrate with the device and with other installed apps.
Advantages of Progressive Web Apps
Despite some limitations in accessing a device’s native capabilities, PWAs offer several significant advantages:
- Reliability: PWAs can function offline and provide a stable experience regardless of network conditions.
- Security: Every PWA must have SSL certificates, ensuring secure user information.
- Speed: PWAs use caching through service workers and device resources to offer fast and seamless experiences.
- Engagement: PWAs integrate well with web and device interfaces, making them highly interactive.
- Ease of Installation: Users can save PWAs to their home screens without the need for downloading, allowing faster loading on subsequent uses.
Another significant advantage of PWAs is users can save them on their home screens without the hassle of downloading. This allows the PWA to load faster the next time it’s used.
Why Should I Use Progressive Web Apps?
Users often prefer apps due to their superior experiences compared to web applications. However, developing and maintaining native apps for different platforms (Android, iOS, etc.) is costly and labor-intensive. PWAs address this by adhering to the "code once, use everywhere" philosophy, allowing a single codebase to work across browsers, desktops, and mobile devices.
The Screen Orientation Problem
To ensure the best user experience, PWAs may need to lock the screen orientation. For example:
- Gaming Apps: Many games are best played in landscape mode.
- Reading Apps: Reading content is often more comfortable in portrait mode.
- Video Apps: Videos are usually better viewed in landscape mode.
Locking the screen orientation helps maintain the intended user experience without unexpected changes when the device is rotated.
What is manifest.json?
If you are working on Progressive Web Apps (PWAs), you should be familiar with manifest.json. This simple JSON file contains all the necessary information required to save a web app to a user's mobile home screen and defines how it will look in terms of user experience — launch screen, theme color, icons,and more.
Key Elements of manifest.json
The keys in manifest.json are essential for configuring various aspects of your PWA. These keys include:
name: The name of your web app.short_name: A shorter version of the name, used when there is insufficient space to display the full name.start_url: The URL that loads when the app is launched.display: The display mode, such as fullscreen, standalone, minimal-ui, or browser.background_color: The background color for the splash screen.theme_color: The theme color for the browser.icons: An array of icons in various sizes.orientation: The default orientation for your app (portrait or landscape) ..etc
For a comprehensive list of keys, refer to the Manifest.json key list.
Controlling Screen Orientation with the Orientation Key
The orientation key in manifest.json allows you to control the screen orientation of your app, which is useful for apps that need to support a specific orientation.
Orientation Values
any: Allows the app to be viewed in any orientation (portrait-primary, portrait-secondary, landscape-primary, landscape-secondary).portrait: The screen height is greater than the width, including both portrait-primary and portrait-secondary.landscape: The screen width is greater than the height, including both landscape-primary and landscape-secondary.portrait-primary: The primary portrait mode, corresponding to 0 degrees if the natural orientation is portrait.portrait-secondary: The secondary portrait orientation, corresponding to 180 degrees if the natural orientation is portrait.landscape-primary: The primary landscape mode, corresponding to 90 degrees clockwise if the natural orientation is portrait.landscape-secondary: The secondary landscape mode, corresponding to 90 degrees counterclockwise if the natural orientation is portrait.
Example
To enforce a specific orientation, include the orientation key in your manifest.json file like this:
Including manifest.json in Your Web App
To include the manifest.json file in your web app, add the following <link> tag inside the <head> section of your HTML document:
Browser Compatibility
The orientation lock feature specified in the manifest.json file is supported by many modern browsers. Refer to the browser compatibility MDN Web Docs chart for detailed information.
For the most up-to-date compatibility information, visit MDN Web Docs.
Conclusion
Controlling screen orientation directly through the PWA's manifest.json file is a straightforward and efficient approach to enhance the user experience. By specifying the desired orientation, such as portrait-primary, you can ensure that your app maintains the intended layout and usability across different devices and browsers.
Key Benefits of Using the manifest.json File for Orientation Control
- Simplicity: Implementing screen orientation control is as simple as adding a single line of code to your manifest.json file, making it accessible even for developers with basic web development skills.
- Consistency: This method ensures consistent behavior across various platforms and devices, reducing the risk of unexpected orientation changes that can disrupt the user experience.
- Efficiency: By setting the orientation in the manifest.json file, you avoid the need for additional code or libraries, streamlining the development process and keeping your codebase clean.
Utilizing the orientation key in manifest.json not only simplifies the development process but also significantly enhances the user experience. Whether you are developing a game, a reading app, or a video player, locking the screen orientation can make your app feel more polished and professional.
For more detailed information and up-to-date compatibility, refer to resources such as MDN Web Docs, which offer comprehensive guides and documentation.
