# Responsive Viewports

**Browser Swarm** enables precise control over browser viewport dimensions, allowing you to simulate various devices and screen sizes. This is essential for testing responsive designs, ensuring consistent user experiences across desktops, tablets, and mobile devices.

***

### 🎯 Why Viewport Control Matters

Modern web applications must adapt seamlessly to a multitude of devices. By customizing viewport settings, you can:

* **Test Responsive Layouts**: Validate how your application renders on different screen sizes.
* **Simulate Specific Devices**: Emulate devices like iPhones, iPads, or Android phones by matching their screen dimensions.
* **Ensure UI Consistency**: Detect and fix layout issues that may arise on varying viewports.

Proper viewport configuration is crucial for delivering a polished and accessible user interface.

***

### ⚙️ Configuring Viewports in Browser Swarm

You can set custom viewport dimensions when creating a browser session using the SDKs.

#### Example

{% tabs %}
{% tab title="Node.js" %}

```javascript
import { BrowserSwarm } from 'browser-swarm-sdk';

const bs = new BrowserSwarm({ apiKey: process.env.BROWSER_SWARM_API_KEY });

const session = await bs.sessions.create({
  projectId: process.env.BROWSER_SWARM_PROJECT_ID,
  browserSettings: {
    viewport: { width: 375, height: 667 }, // iPhone 8 dimensions
    userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5 like Mac OS X)...',
  },
});
```

{% endtab %}

{% tab title="Python" %}

```python
from browser_swarm import BrowserSwarm
import os

bs = BrowserSwarm(api_key=os.environ["BROWSER_SWARM_API_KEY"])

session = bs.sessions.create(
    project_id=os.environ["BROWSER_SWARM_PROJECT_ID"],
    browser_settings={
        "viewport": {"width": 375, "height": 667},  # iPhone 8 dimensions
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_5 like Mac OS X)...",
    },
)
```

{% endtab %}
{% endtabs %}

*Note: Adjust the `userAgent` string to match the device you're simulating for more accurate emulation.*

***

### 📐 Common Device Viewport Dimensions

Here are some standard viewport sizes for popular devices:

| Device          | Width | Height |
| --------------- | ----- | ------ |
| iPhone SE       | 375   | 667    |
| iPhone 12 Pro   | 390   | 844    |
| Pixel 5         | 393   | 851    |
| iPad Pro 11"    | 834   | 1194   |
| MacBook Pro 13" | 1280  | 800    |
| Desktop 1080p   | 1920  | 1080   |

Using these dimensions helps in testing how your application behaves across different devices.

***

### 🧪 Testing Responsive Designs

To ensure your application is responsive:

1. **Set the Viewport**: Configure the desired viewport dimensions during session creation.
2. **Navigate to Your Application**: Use automation frameworks like Playwright, Puppeteer, or Selenium to load your application.
3. **Perform Visual Checks**: Capture screenshots or use visual testing tools to verify layout and design consistency.
4. **Automate Tests**: Write automated tests that assert the presence and positioning of critical UI elements.

Regularly testing across multiple viewports ensures a consistent user experience.

***

### 🖼️ Visual Regression Testing

Integrate visual regression testing tools to detect unintended changes in your application's appearance across different viewports. Tools like Percy or Applitools can be integrated into your CI/CD pipeline to automate this process.

***

### 💡 Best Practices

* **Combine Viewport and User Agent**: To accurately simulate a device, set both the viewport dimensions and the corresponding user agent string.
* **Test Critical Breakpoints**: Focus on common breakpoints (e.g., 320px, 768px, 1024px, 1440px) to cover a wide range of devices.
* **Automate Testing**: Incorporate viewport tests into your automated testing suite to catch issues early.
* **Use Real Devices When Possible**: While emulation is helpful, testing on actual devices can reveal issues that emulators might miss.

By following these practices, you can ensure your application provides a seamless experience across all devices.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://browserswarm.gitbook.io/docs/responsive-viewports.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.