# Cropping issues
Why your image isn’t cropping to the size you expect
* * *
## How Auto-Cropping Works
The HTML/CSS to Image API has a powerful **auto-cropping** feature that automatically sizes your image to match your HTML content. When you send an HTML snippet, the API crops the resulting image to the dimensions of the **outermost HTML element**.
However, this only works for **HTML snippets**—not full HTML pages.
Auto-cropping
Send an HTML snippet to crop to the outermost element. A full document renders the viewport; use a `selector` to target an element within it.
* * *
## The Most Common Mistake
The most frequent cropping issue we see: **sending a full HTML page when you meant to send an HTML snippet**.
### What Happens with a Full HTML Page
When you include ``, ``, ``, or `` tags, the API treats your content as a **full webpage** and renders it inside the default viewport (1920x1080 pixels).
**Example of what NOT to do:**
```html
My Card
This should be 400x200
```
**Result:** Instead of a 400x200 image, you get a 1920x1080 image with your content in the corner:
Notice how the image includes the entire viewport with a gray background, not just your 400x200 card.
* * *
## The Solution: Use HTML Snippets
Remove the ``, ``, ``, and `` tags. Send only the HTML elements you want in your image.
**The correct approach:**
```html
My Card
Correctly sized 400x200
```
**Result:** The image is cropped to the element’s border box. With default `content-box` sizing, a 2px border adds 4px to each dimension. Add `box-sizing: border-box` for exactly 400×200 CSS pixels, or 800×400 output pixels at 2x resolution.
* * *
## Setting Dimensions on the Outermost Element
For auto-cropping to work correctly, set explicit `width` and `height` on your **outermost** HTML element:
```html
```
The API will crop the image to match these dimensions (doubled for retina displays by default).
### Using CSS Classes
You can also use a `
Welcome
Your styled content here
```
* * *
## Adding Margins Around Your Image
Need some breathing room around your content? Add `margin` to the outermost element. The auto-cropper respects margins and includes them in the final image.
### Without Margin
```html
No Margin
Cropped tightly to edges
```
### With Margin
```html
With Margin
20px space around
```
Notice the transparent space around the card when using `margin: 20px`. This is useful for adding padding around social cards, thumbnails, or any image that needs visual breathing room.
* * *
## When You Need Full HTML Pages
Sometimes you do need to send a full HTML page—for example, when including external libraries, complex CSS, or JavaScript. In these cases, use the [`viewport_width` and `viewport_height` parameters](/parameters/viewport/#viewport-width-and-height) to control the image size:
```json
{
"html": "...",
"viewport_width": 400,
"viewport_height": 200
}
```
Or use the `selector` parameter to crop to a specific element within the page:
```json
{
"html": "......
...",
"selector": "#card"
}
```
Learn more about the [selector parameter](/parameters/selector/).
* * *
## Quick Troubleshooting Checklist
If your image isn’t cropping correctly, work through these steps:
1. **Remove full page tags** — Delete ``, ``, ``, and `` tags
2. **Set explicit dimensions** — Add `width` and `height` to your outermost element
3. **Check for wrapper elements** — Ensure no invisible wrapper is affecting dimensions
4. **Use viewport params for full pages** — If you must use a full page, set `viewport_width` and `viewport_height`
5. **Try the selector param** — Use `selector` to crop to a specific element
* * *
## Summary
| Scenario | Solution |
| --- | --- |
| Image is full viewport size (1920x1080) | Remove ``, `` tags—use HTML snippet |
| Image size doesn’t match your CSS | Set `width` and `height` on outermost element |
| Need space around the image | Add `margin` to the outermost element |
| Must use full HTML page | Use `viewport_width`/`viewport_height` or `selector` param |
## Need help?
Talk to a human. Email [support@htmlcsstoimage.com](mailto:support@htmlcsstoimage.com) and we’ll help you get started.