All rules

Sheath rule

a11y-no-non-scalable-viewport

Viewport must allow user scaling for accessibility.
Package
Core
Category
Accessibility
Default severity
error by default
Auto-fix
Auto-fix available

(dangerous)

#Why

Preventing users from zooming on mobile devices is an accessibility issue. Users with low vision may need to zoom in to read content. The following values restrict scaling and are reported:

  • user-scalable=no
  • unknown user-scalable values, which viewport processing converts to a fixed scale
  • a numeric maximum-scale below 2
  • maximum-scale=yes, which viewport processing translates to 1
  • maximum-scale=no and unknown values, which viewport processing translates to 0.1

These settings violate WCAG 2.2 Success Criterion 1.4.4 (Resize Text).

The fixer removes the restrictive viewport settings. This is dangerous and requires --dangerous, because it changes the user's zoom interaction.

#Examples

#Bad

<!-- Disabling user scaling -->

<meta name="viewport" content="width=device-width, user-scalable=no">



<!-- user-scalable=0 also disables scaling -->

<meta name="viewport" content="width=device-width, user-scalable=0">



<!-- Maximum scale of 1 prevents zooming -->

<meta name="viewport" content="width=device-width, maximum-scale=1.0">



<!-- Maximum scale below 2 prevents the required 200% zoom -->

<meta name="viewport" content="width=device-width, maximum-scale=1.5">



<!-- The special yes value translates to a maximum scale of 1 -->

<meta name="viewport" content="width=device-width, maximum-scale=yes">



<!-- Combination that prevents zooming -->

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">

#Good

<!-- Allow user scaling (default) -->

<meta name="viewport" content="width=device-width, initial-scale=1">



<!-- Explicitly allowing scaling -->

<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=yes">



<!-- Allow zooming up to 5x -->

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">



<!-- No maximum-scale restriction -->

<meta name="viewport" content="width=device-width">

#Notes

  • The default browser behavior allows zooming - don't override it
  • If your design "breaks" when zoomed, fix the design rather than preventing zoom
  • Use relative units (em, rem, %) for better responsive scaling
  • Test your site at 200% and 400% zoom levels
  • A static maximum-scale uses the browser's leading-number parsing. Values such as 1.5foo therefore still impose a scale below 2 and are reported; device-width and device-height translate to 10, negative values are dropped, and other non-numeric values translate to 0.1. Dynamic values are left alone
  • Viewport properties may be separated by HTML whitespace as well as commas or semicolons. Repeated properties use the last declaration, matching CSS descriptor cascading; a dangerous fix removes every earlier occurrence that could otherwise become effective

#References

#Related Rules