# Blurry images

Understand pixel density and choose the right resolution for your images.

## Why Images Look Blurry

Blurry images are almost always caused by **insufficient pixel density** for the display they’re viewed on. Modern screens—especially smartphones, tablets, and high-resolution monitors—pack many more pixels into the same physical space than older displays.

The HTML/CSS to Image API automatically generates **high-resolution images by default** to ensure your images look crisp on all devices. Here’s everything you need to know about creating pixel-perfect images.

Default resolution

HTML images default to `device_scale: 2`. URL screenshots default to `1`; set `device_scale: 2` when you need a higher-resolution screenshot.

## Understanding Pixel Density

### The Modern Display Challenge

Today’s screens vary dramatically in pixel density:

*   **Standard displays**: 1 physical pixel = 1 CSS pixel (1x)
*   **Retina/High-DPI displays**: 2-4 physical pixels = 1 CSS pixel (2x-4x)
*   **Ultra-high resolution**: 3+ physical pixels = 1 CSS pixel (3x+)

When you create an image at standard resolution (1x) and display it on a high-density screen, the browser must **stretch** those pixels to fill the available space—resulting in a blurry, pixelated appearance.

### The 2x Rule Explained

The **2x rule** is simple: **create images at double your intended display size**.

**Example:**

*   Display size needed: `400×400px`
*   Image source size: `800×800px` (2x)
*   Result: Sharp image on all screens

This ensures you have enough pixel data to satisfy high-density displays while still looking great on standard screens.

## Device Scale Settings

The HCTI API uses the `device_scale` parameter to control image resolution:

| Setting | Resolution | Use Case | File Size |
| --- | --- | --- | --- |
| `1` | Standard (1x) | Legacy screens, thumbnails | Smallest |
| `2` | High (2x) | **Recommended for web** | Medium |
| `3` | Maximum (3x) | Print, premium displays | Largest |

### Default Behavior

*   **HTML images**: `device_scale: 2` (high resolution by default)
*   **URL screenshots**: `device_scale: 1` (standard resolution)

## Common Causes of Blurry Images

### 1\. Insufficient Source Image Resolution

**Problem**: Your source images are too small for high-DPI rendering.

**Example**: Using a `200×200px` image that needs to display at `200×200px` on a 2x display.

**Solution**: Use source images at 2x your display size:

```html
<!-- Instead of this -->
<img src="logo-200x200.png" width="200" height="200">


<!-- Use this -->
<img src="logo-400x400.png" width="200" height="200">
```

### 2\. Incorrect Device Scale for URLs

**Problem**: URL screenshots default to `device_scale: 1`.

**Solution**: Explicitly set `device_scale: 2` for URL images:

```json
{
  "url": "https://example.com",
  "device_scale": 2
}
```

### 3\. Mixed Resolution Assets

**Problem**: Some images in your HTML are high-resolution while others are not.

**Solution**: Ensure ALL images follow the 2x rule:

```html
<!-- Good: All images are 2x their display size -->
<img src="header-800x200.png" width="400" height="100">
<img src="logo-200x200.png" width="100" height="100">
<img src="photo-1200x800.png" width="600" height="400">
```

## Step-by-Step Debugging

### Step 1: Check Your Device Scale

For HTML images, verify your API request:

```json
{
  "html": "<div>Your content</div>",
  "device_scale": 2
}
```

For URL images, always specify device scale:

```json
{
  "url": "https://your-site.com",
  "device_scale": 2
}
```

### Step 2: Audit Your Source Images

Calculate if your images meet the 2x requirement:

1.  **Intended display size**: How big will the image appear? (e.g., 300px wide)
2.  **Required source size**: Multiply by device scale (300px × 2 = 600px wide)
3.  **Actual source size**: Check your image file dimensions

**Quick audit checklist:**

*   [ ]  All images are 2x their CSS display size
*   [ ]  External images from CDNs have high-res versions
*   [ ]  Icons and logos have sufficient resolution
*   [ ]  Background images are appropriately sized

### Step 3: Test on Different Displays

View your generated image on:

*   Standard resolution monitor
*   High-DPI laptop screen (MacBook, high-end Windows laptops)
*   Mobile device (iPhone, Android phone)
*   Tablet (iPad, Android tablet)

The image should look equally sharp on all devices.

## Real-World Examples

### Example 1: Social Media Card

**Bad approach:**

```html
<div style="width: 1200px; height: 630px;">
  <img src="avatar-150x150.jpg" width="150" height="150">
  <!-- Image will be blurry on high-DPI displays -->
</div>
```

**Good approach:**

```html
<div style="width: 1200px; height: 630px;">
  <img src="avatar-300x300.jpg" width="150" height="150">
  <!-- Image will be sharp on all displays -->
</div>
```

### Example 2: Company Logo

**Bad approach:**

```css
.logo {
  width: 200px;
  height: 60px;
  background-image: url('logo-200x60.png');
}
```

**Good approach:**

```css
.logo {
  width: 200px;
  height: 60px;
  background-image: url('logo-400x120.png');
  background-size: 200px 60px; /* Scale down to intended size */
}
```

## Advanced Techniques

### Responsive Images with srcset

For external images, use responsive image techniques:

```html
<img src="photo-600x400.jpg"
     srcset="photo-600x400.jpg 1x, photo-1200x800.jpg 2x"
     width="600" height="400">
```

### CSS Media Queries for High-DPI

Target high-resolution displays specifically:

```css
@media only screen and (-webkit-min-device-pixel-ratio: 2),
       only screen and (min-resolution: 192dpi) {
  .hero-image {
    background-image: url('hero-2x.jpg');
  }
}
```

### Vector Graphics for Perfect Scaling

Use SVG for logos and icons that scale perfectly at any resolution:

```html
<img src="logo.svg" width="200" height="60">
<!-- SVG automatically scales to any device -->
```

## Performance Considerations

### File Size Impact

Higher resolution increases pixel count; compressed file size also depends on content and format:

*   `device_scale: 1` → Base pixel count
*   `device_scale: 2` → 4x as many pixels
*   `device_scale: 3` → 9x as many pixels

### Optimization Strategies

1.  **Use appropriate compression**: Balance quality vs. file size
2.  **Choose the right format**:
    *   PNG for graphics with transparency
    *   JPG for photographs
    *   WebP for modern browsers (when supported)
3.  **Consider bandwidth**: Higher resolution may impact load times

Performance tip

Start with `device_scale: 2` for web images, then check sharpness and file size at the intended display size.

## Troubleshooting Checklist

When your image still looks blurry:

*   [ ]  **Device scale is set to 2** (for HTML) or explicitly specified (for URLs)
*   [ ]  **All source images are 2x their display size**
*   [ ]  **External CDN images have high-resolution versions available**
*   [ ]  **CSS background images use appropriately sized sources**
*   [ ]  **Vector graphics (SVG) are used where possible**
*   [ ]  **The generated image is being displayed at the correct size**

## Browser Testing

Test your images across different scenarios:

```html
<!-- Test HTML - put this in your browser -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
    <h1>Image Quality Test</h1>


    <!-- Your generated image -->
    <img src="your-generated-image.png" width="400" height="300">


    <!-- View at different sizes -->
    <img src="your-generated-image.png" width="200" height="150">
    <img src="your-generated-image.png" width="800" height="600">
</body>
</html>
```

## Need Help?

Still experiencing blurry images? We’re here to help debug your specific case.

**Email us**: [support@htmlcsstoimage.com](mailto:support@htmlcsstoimage.com)

Include:

*   Your API request (HTML/CSS or URL)
*   Expected vs. actual results
*   What devices/screens you’re testing on
*   Any specific requirements for your use case

We love solving tricky rendering problems and helping you achieve pixel-perfect results.