Orientation

The orientation property controls the default screen orientation when your PWA is launched. This ensures your application displays optimally based on its content and intended user experience.

Purpose

Screen orientation affects:

User interface layout: How content is arranged on screen
User experience: Natural interaction patterns for your app type
Media consumption: Optimal viewing for videos, games, or documents
Device ergonomics: How users hold and interact with their device

Configuration

/config/packages/pwa.yaml

pwa:
    manifest:
        enabled: true
        orientation: "portrait"  # or landscape, any, etc.

If not specified, the orientation defaults to any, allowing the device to rotate freely.

Available Orientations

any (Default)

Allows the application to rotate freely based on device orientation.

orientation: "any"

Best for:

Multi-purpose applications
Apps with responsive layouts
Content that works well in both orientations
Most general-purpose apps

Examples: Social media apps, news readers, general productivity tools

portrait

Locks to portrait orientation (vertical), allowing both normal and inverted portrait.

orientation: "portrait"

Best for:

Reading-focused applications
Social media feeds
Chat applications
Form-heavy applications
One-handed mobile use

Examples:

Instagram-like photo sharing
Messaging apps
News articles
Shopping apps with vertical scrolling

portrait-primary

Locks to the device's primary portrait orientation (typically upright, not inverted).

orientation: "portrait-primary"

Best for:

Applications requiring consistent UI position
Apps using device sensors
Camera-based applications
Applications with fixed control positions

Examples:

Camera apps
QR code scanners
Fitness tracking apps
Applications with bottom navigation

landscape

Locks to landscape orientation (horizontal), allowing both left and right landscape.

orientation: "landscape"

Best for:

Video playback applications
Games
Presentation tools
Media consumption
Spreadsheets or wide data views

Examples:

Video streaming apps
Gaming platforms
Dashboard applications
Photo galleries

landscape-primary

Locks to the device's primary landscape orientation.

orientation: "landscape-primary"

Best for:

Games with specific control layouts
Applications using device sensors in landscape
Car dashboard apps
Presentation apps

Examples:

Racing games
Flight simulators
Car navigation apps
DJ/Music production apps

Use Cases by Application Type

pwa:
    manifest:
        name: "SocialConnect"
        orientation: "portrait"  # Vertical scrolling is natural

Rationale: Content feeds are designed for vertical scrolling, and users typically hold phones in portrait mode.

Video Streaming App

pwa:
    manifest:
        name: "StreamFlix"
        orientation: "any"  # Switch to landscape for fullscreen

Rationale: Browse in portrait, watch videos in landscape. Flexibility is key.

Gaming App

pwa:
    manifest:
        name: "SpaceRacer"
        orientation: "landscape-primary"  # Fixed game controls

Rationale: Game controls are designed for landscape, and consistency is crucial.

E-book Reader

pwa:
    manifest:
        name: "BookReader"
        orientation: "portrait-primary"  # Reading comfort

Rationale: Reading text is more comfortable in portrait mode, mimicking physical books.

Dashboard App

pwa:
    manifest:
        name: "Analytics Dashboard"
        orientation: "landscape"  # More horizontal space for charts

Rationale: Charts and data visualizations benefit from wider screens.

Fitness Tracker

pwa:
    manifest:
        name: "FitTrack"
        orientation: "portrait-primary"  # One-handed use during exercise

Rationale: Users often interact while exercising, requiring one-handed portrait mode.

Complete Examples

Portrait-Only Application

pwa:
    manifest:
        name: "ChatApp"
        short_name: "Chat"
        orientation: "portrait"
        display: "standalone"
        theme_color: "#2196F3"
        description: "Stay connected with friends and family through instant messaging."

Landscape-Only Application

pwa:
    manifest:
        name: "VideoEditor"
        short_name: "Editor"
        orientation: "landscape"
        display: "fullscreen"
        theme_color: "#FF5722"
        description: "Create and edit videos with professional tools."

Flexible Orientation Application

pwa:
    manifest:
        name: "TaskManager"
        short_name: "Tasks"
        orientation: "any"  # Adapts to user preference
        display: "standalone"
        theme_color: "#4CAF50"
        description: "Organize your tasks and boost productivity."

Platform Behavior

iOS (iPhone/iPad)

Respects orientation lock if device rotation is disabled in settings
portrait-primary and landscape-primary may behave differently based on device
iPad may ignore orientation locks in some contexts
Supports all standard orientations

Android

Strongly respects manifest orientation
Users can override with device settings
Different behavior in tablet vs phone mode
Chrome and other browsers may handle differently

Desktop/Laptop

Orientation setting is typically ignored
Windows treated as landscape by default
Application runs in window mode
Resizing window doesn't trigger orientation changes

Best Practices

1. Choose Based on Content

Match orientation to your primary use case:

# Reading app - portrait is natural
orientation: "portrait"

# Video app - allow both
orientation: "any"

# Game - lock to landscape
orientation: "landscape-primary"

2. Consider User Context

Think about how users will hold their device:

One-handed use: portrait or portrait-primary
Two-handed comfortable viewing: landscape
Variable situations: any

3. Test on Real Devices

Different devices handle orientation differently:

# Test on various devices
- iPhone (small)
- iPad (large, different aspect ratio)
- Android phone (various sizes)
- Android tablet
- Desktop browser

4. Provide Responsive Design Regardless

Even with orientation lock, design responsively:

/* Support both orientations in CSS */
@media (orientation: portrait) {
    /* Portrait-specific styles */
}

@media (orientation: landscape) {
    /* Landscape-specific styles */
}

5. Don't Lock Unnecessarily

Only lock orientation when truly needed:

# ✗ Poor - locks without reason
orientation: "portrait"  # For a general-purpose app

# ✓ Good - allows natural rotation
orientation: "any"  # For a general-purpose app

Advanced: Handling Orientation Changes

Even with a locked orientation in the manifest, handle rotation in your JavaScript:

// Listen for orientation changes
window.addEventListener('orientationchange', () => {
    const orientation = screen.orientation.type;
    console.log('Orientation changed to:', orientation);

    // Adjust UI accordingly
    if (orientation.includes('portrait')) {
        adjustForPortrait();
    } else {
        adjustForLandscape();
    }
});

// Or use matchMedia
const isPortrait = window.matchMedia('(orientation: portrait)');

isPortrait.addEventListener('change', (e) => {
    if (e.matches) {
        console.log('Now in portrait mode');
    } else {
        console.log('Now in landscape mode');
    }
});

Accessibility Considerations

1. Don't Restrict User Choice

Some users have accessibility needs requiring specific orientations:

Motor disabilities: May need landscape for larger touch targets
Visual impairments: May prefer portrait for easier reading
Physical limitations: May only be able to hold device one way

Recommendation: Use any unless orientation lock is essential.

2. Provide Clear Feedback

If your app requires a specific orientation, inform users:

// Show message if user is in wrong orientation
if (requiredOrientation === 'landscape' && isPortrait()) {
    showRotationPrompt('Please rotate your device to landscape mode');
}

3. Test with Screen Readers

Ensure orientation changes don't disrupt screen reader navigation:

<!-- Announce orientation changes -->
<div role="status" aria-live="polite" id="orientation-status"></div>

<script>
window.addEventListener('orientationchange', () => {
    document.getElementById('orientation-status').textContent =
        `Screen orientation changed to ${screen.orientation.type}`;
});
</script>

Common Mistakes

1. Locking When Not Needed

# ✗ Poor - unnecessary restriction
pwa:
    manifest:
        name: "GeneralApp"
        orientation: "portrait"  # No specific reason

Impact: Frustrates users who want to use landscape mode.

2. Wrong Orientation for Content

# ✗ Poor - video app locked to portrait
pwa:
    manifest:
        name: "VideoApp"
        orientation: "portrait"  # Videos are better in landscape

Impact: Poor user experience for primary use case.

3. Not Testing Both Orientations

Even with a locked orientation, test your layout in both:

Users may override in settings
Tablets behave differently
Desktop windows can be any size

4. Ignoring CSS Media Queries

Manifest orientation doesn't replace responsive CSS:

/* ✓ Still implement responsive design */
@media (orientation: landscape) {
    .content { flex-direction: row; }
}

@media (orientation: portrait) {
    .content { flex-direction: column; }
}

Debugging Orientation

1. Check Manifest in DevTools

# Chrome DevTools
1. Open DevTools (F12)
2. Go to Application tab
3. Select "Manifest" in sidebar
4. Check "orientation" value

2. Test Orientation Lock

// Check current orientation
console.log('Type:', screen.orientation.type);
console.log('Angle:', screen.orientation.angle);

// Available types:
// - portrait-primary (0°)
// - portrait-secondary (180°)
// - landscape-primary (90° or -90°)
// - landscape-secondary (-90° or 90°)

3. Simulate on Desktop

Chrome DevTools device emulation:

1. Open DevTools
2. Click device toolbar icon (Ctrl+Shift+M)
3. Select device
4. Click rotation icon to toggle orientation

Display Mode - How the app window is presented
Theme Color - Visual appearance
Scope - URL scope for the app

Summary

Orientation best practices:

✓ Use any unless you have a specific reason to lock
✓ Match orientation to your primary use case (video → landscape, reading → portrait)
✓ Test on real devices in both orientations
✓ Provide responsive CSS regardless of manifest setting
✓ Consider accessibility needs before locking orientation
✓ Inform users if a specific orientation is required
✗ Don't lock orientation unnecessarily
✗ Don't forget to test orientation changes even when locked

PreviousDirection and Language NextDescription

Last updated 5 days ago

Was this helpful?

Purpose

Configuration

Available Orientations

any (Default)

portrait

portrait-primary

landscape

landscape-primary

Use Cases by Application Type

Social Media App

Video Streaming App

Gaming App

E-book Reader

Dashboard App

Fitness Tracker

Complete Examples

Portrait-Only Application

Landscape-Only Application

Flexible Orientation Application

Platform Behavior

iOS (iPhone/iPad)

Android

Desktop/Laptop

Best Practices

1. Choose Based on Content

2. Consider User Context

3. Test on Real Devices

4. Provide Responsive Design Regardless

5. Don't Lock Unnecessarily

Advanced: Handling Orientation Changes

Accessibility Considerations

1. Don't Restrict User Choice

2. Provide Clear Feedback

3. Test with Screen Readers

Common Mistakes

1. Locking When Not Needed

2. Wrong Orientation for Content

3. Not Testing Both Orientations

4. Ignoring CSS Media Queries

Debugging Orientation

1. Check Manifest in DevTools

2. Test Orientation Lock

3. Simulate on Desktop

Related Properties

Summary