Image aspect ratio mismatch: attributes versus the CSS box
When width and height describe one ratio and CSS forces another, the image stretches. squirrel compares the two and allows for object-fit.
What an aspect ratio mismatch is
An <img> can have its ratio declared twice: once by the width and height attributes, and once by CSS, either through an explicit aspect-ratio or through a fixed width and height in pixels. A disagreement is a distortion risk rather than a certainty: with a fixed width and height the image is stretched to fill the box, while aspect-ratio has no effect when both dimensions are already definite.
object-fit is the escape hatch. cover, contain, scale-down and none all preserve the image’s natural proportions inside the box, whether by cropping, by leaving space around it, or by not resizing it at all. A mismatch under any of those is deliberate rather than a bug.
What squirrel checks
The rule runs on every crawled page over every img[style], so an image with no inline style is not examined. It needs integer width and height attributes and an inline style that fixes a ratio, either an aspect-ratio declaration or both width and height in px.
- Warn when the two ratios differ by more than
tolerance, as a fraction of the attribute ratio. Message:2 image(s) with conflicting attribute vs CSS aspect ratio (distortion risk), each item labelled/photo.jpg (1200x800 attr vs 1.00:1 CSS)with a markup snippet. Up to ten items are listed. Severity warning, weight 4. - Pass otherwise. Message:
No conflicting image aspect ratios detected.
An image is skipped when its inline style sets object-fit to cover, contain, scale-down or none, or when its class attribute contains one of object-cover, object-contain, object-scale-down or object-none. External stylesheets cannot be read, so a utility class is the only signal available for class-based object-fit.
Elements inside <noscript> are skipped: a browser with scripting enabled reads <noscript> content as plain text, so nothing in it loads or renders. See content inside noscript.
How to fix it
<img src="/photo.jpg" width="1200" height="800" alt="…" style="width:600px;height:400px" />Make the two agree, or set the width in CSS with height: auto so the height follows the ratio. A CSS width alone does not do it while a height attribute is still in play. Where the crop is deliberate, add object-fit: cover so the image fills the box without distortion.
An image styled through an external stylesheet cannot be checked, because the rule only reads inline styles.
| Rule ID | images/aspect-mismatch |
| Category | Images |
| Scope | Per-page |
| Severity | warning |
| Weight | 4/10 |
Options
| Option | Type | Default | Description |
|---|---|---|---|
tolerance | number | 0.05 | Allowed fractional difference between the two aspect ratios |
Configuration example
[rule_options."images/aspect-mismatch"]
tolerance = 0.02Enable / disable
Disable this rule
[rules]
disable = ["images/aspect-mismatch"]Disable all Images rules
[rules]
disable = ["images/*"]Enable only this rule
[rules]
enable = ["images/aspect-mismatch"]enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.
Related rules
- images/dimensions: the attributes this rule compares against.
- images/responsive-size: thumbnail-sized images whose files are heavier than their displayed size needs.
- perf/cls-hints: the layout shift the same attributes prevent.
- images/srcset: serving a file that matches the rendered box.
Images findings ship in every audit next to the SEO, performance and agent experience rules. See Core Web Vitals for how an agent works through a report.
References
Check your site
Run squirrel audit https://example.com and open the Images section of the report. Each mismatch is listed with both ratios and a markup snippet. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.