Skip to main content
Configure which screen orientations your NativePHP Mobile app supports on iOS and Android. Control portrait and landscape modes for different device types.

​
Configuration

Screen orientation is configured in config/nativephp.php: 
'orientation' => [
    'iphone' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => false,
        'landscape_right' => false,
    ],
    'android' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => false,
        'landscape_right' => false,
    ],
],

​
Applying Changes

After modifying orientation settings, rebuild the native configuration: 
php artisan native:install --force
php artisan native:run

​
Orientation Options

Each platform supports four orientation modes:

​
Portrait

Standard vertical orientation with the device held upright: 
'portrait' => true,
When to use:
  • Most mobile apps
  • Content-focused apps (news, social media)
  • Forms and data entry
  • Apps with vertical scrolling

​
Upside Down

Inverted portrait orientation (device rotated 180 degrees): 
'upside_down' => false, // Usually disabled
When to use:
  • Rarely used on iPhones (typically disabled)
  • May be useful for specialized use cases
Apple recommends disabling upside-down portrait on iPhones to avoid accidental rotation.

​
Landscape Left

Horizontal orientation with the home button on the left (or device tilted left): 
'landscape_left' => true,
When to use:
  • Video playback
  • Games
  • Dashboard and data visualization apps
  • Apps with wide content

​
Landscape Right

Horizontal orientation with the home button on the right (or device tilted right): 
'landscape_right' => true,
When to use:
  • Video playback (usually combined with landscape_left)
  • Games
  • Apps requiring horizontal viewing
For landscape apps, enable both landscape_left and landscape_right to support rotation in either direction.

​
Platform-Specific Behavior

​
iPhone

iPhone orientation is configured independently from iPad: 
'orientation' => [
    'iphone' => [
        'portrait' => true,
        'upside_down' => false,      // Typically disabled
        'landscape_left' => false,
        'landscape_right' => false,
    ],
],
Requirements:
  • At least one orientation must be enabled
  • Upside-down portrait is typically disabled
  • Settings apply to all iPhone models

​
iPad

iPad support is controlled by the ipad configuration option: 
'ipad' => true,
When iPad support is enabled:
  • All orientations are automatically supported (portrait, upside down, landscape left, landscape right)
  • This is required by Apple’s App Store guidelines
  • You cannot selectively disable iPad orientations
Once an app is deployed to the App Store with iPad support, you cannot remove iPad support in future updates.
When to enable iPad support:
  • Your app UI scales well to larger screens
  • You want to reach iPad users
  • Your app provides a good experience on tablets
When to keep iPad support disabled:
  • Your app is designed specifically for phone-sized screens
  • You’re not ready to support tablet layouts
  • You want to limit your app to iPhones initially

​
Android

Android orientation is configured independently: 
'orientation' => [
    'android' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => false,
        'landscape_right' => false,
    ],
],
Requirements:
  • At least one orientation must be enabled
  • Settings apply to all Android devices (phones and tablets)
  • Upside-down portrait is less common on Android

​
Common Configurations

​
Portrait Only (Default)

Most mobile apps use portrait-only orientation: 
'orientation' => [
    'iphone' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => false,
        'landscape_right' => false,
    ],
    'android' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => false,
        'landscape_right' => false,
    ],
],
'ipad' => false,
Best for:
  • Social media apps
  • News and content apps
  • E-commerce apps
  • Form-heavy apps

​
Landscape Only

For games or horizontal-focused apps: 
'orientation' => [
    'iphone' => [
        'portrait' => false,
        'upside_down' => false,
        'landscape_left' => true,
        'landscape_right' => true,
    ],
    'android' => [
        'portrait' => false,
        'upside_down' => false,
        'landscape_left' => true,
        'landscape_right' => true,
    ],
],
'ipad' => false, // Or true if you want iPad support
Best for:
  • Racing games
  • Horizontal scrolling games
  • Video editing apps
  • Dashboard apps

​
All Orientations

For apps that work well in any orientation: 
'orientation' => [
    'iphone' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => true,
        'landscape_right' => true,
    ],
    'android' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => true,
        'landscape_right' => true,
    ],
],
'ipad' => true, // Automatically supports all orientations
Best for:
  • Video playback apps
  • Photo viewing apps
  • Reading apps
  • Flexible UI apps

​
Portrait with Landscape Video

For portrait apps that support landscape video playback: 
'orientation' => [
    'iphone' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => true,  // For video
        'landscape_right' => true, // For video
    ],
    'android' => [
        'portrait' => true,
        'upside_down' => false,
        'landscape_left' => true,
        'landscape_right' => true,
    ],
],
'ipad' => false,
Best for:
  • Social media apps with video
  • News apps with video content
  • Apps with embedded video players

​
Responsive Design Considerations

When supporting multiple orientations, design your UI to adapt:

​
Using Tailwind CSS Responsive Classes

<!-- Portrait: stacked, Landscape: side-by-side -->
<div class="flex flex-col landscape:flex-row">
    <div class="w-full landscape:w-1/2">Content 1</div>
    <div class="w-full landscape:w-1/2">Content 2</div>
</div>

​
Detecting Orientation in JavaScript

// Check current orientation
const isPortrait = window.matchMedia('(orientation: portrait)').matches;
const isLandscape = window.matchMedia('(orientation: landscape)').matches;

// Listen for orientation changes
window.matchMedia('(orientation: portrait)').addEventListener('change', e => {
    if (e.matches) {
        console.log('Switched to portrait');
    }
});

​
Detecting Orientation in Livewire

use Livewire\Component;

class MyComponent extends Component
{
    public $isPortrait = true;

    #[On('orientation-changed')]
    public function handleOrientationChange($orientation)
    {
        $this->isPortrait = $orientation === 'portrait';
    }
}

// Emit orientation changes to Livewire
window.matchMedia('(orientation: portrait)').addEventListener('change', e => {
    Livewire.dispatch('orientation-changed', {
        orientation: e.matches ? 'portrait' : 'landscape'
    });
});

​
Validation

The build process validates orientation configuration: iPhone validation: 
# At least one iPhone orientation must be enabled
Error: No iPhone orientations enabled. Enable at least one orientation.
Android validation: 
# At least one Android orientation must be enabled
Error: No Android orientations enabled. Enable at least one orientation.

​
Testing Orientations

Test your app in all supported orientations:

​
iOS Simulator

# Rotate simulator
Cmd + Left Arrow  # Landscape left
Cmd + Right Arrow # Landscape right
Cmd + Up Arrow    # Portrait

​
Android Emulator

# Rotate emulator
Ctrl + Left Arrow  # Landscape left
Ctrl + Right Arrow # Landscape right
Ctrl + Up Arrow    # Portrait

​
Physical Devices

Test on real devices with auto-rotate enabled:
  1. Enable auto-rotate in device settings
  2. Physically rotate the device
  3. Verify UI adapts correctly
  4. Check for layout issues

​
Best Practices

Most apps work best in portrait mode. Only add landscape support if your app truly benefits from it.
If you enable landscape mode, enable both left and right to allow natural device rotation.
Remember that iPad support requires all orientations. Only enable iPad if you’re ready to support tablet layouts.
Test your app’s behavior when rotating between orientations to ensure smooth transitions.
Design your UI to adapt gracefully to different orientations using responsive CSS classes.
For iPhones, keep upside-down portrait disabled unless you have a specific use case.

​
Troubleshooting

​
App doesn’t rotate

  1. Verify orientation is enabled in config
  2. Run php artisan native:install --force
  3. Check device auto-rotate is enabled
  4. Rebuild and reinstall the app

​
iPad shows wrong orientations

Remember: When ipad is enabled, all orientations are automatically supported regardless of iPhone settings.

​
Build fails with orientation error

Ensure at least one orientation is enabled for each platform: 
// This will fail:
'iphone' => [
    'portrait' => false,
    'upside_down' => false,
    'landscape_left' => false,
    'landscape_right' => false,
],

// At least one must be true:
'iphone' => [
    'portrait' => true, // ✓
    // ... other orientations
],

​
Next Steps

Configuration

Learn about other configuration options

Responsive Design

Build responsive layouts for different orientations

Build docs developers (and LLMs) love

Get started for freeTalk to us