HTML Guides for max-width

The max-width property sets the maximum width an element can grow to, preventing the computed value of width from exceeding the specified limit. While many CSS sizing properties accept auto as a value (for example, width: auto and margin: auto are perfectly valid), the max-width property does not. This is a common mistake because developers often assume auto is universally accepted across similar properties.

When a browser encounters max-width: auto, it will typically ignore the invalid declaration and fall back to the default value of none. While the page may still render as expected in some browsers, relying on this behavior is unreliable and non-standard. Writing valid CSS ensures consistent rendering across all browsers and makes your stylesheets easier to maintain and debug.

If your intent is to remove a maximum width constraint (effectively making max-width have no effect), use none — this is the default value. If you want the element to size itself based on its content, use max-content, min-content, or fit-content. If you need to reset the property to its initial value, use initial (which resolves to none).

Valid values for max-width

The max-width property accepts the following types of values:

• none — No limit on the element's width (the default).
• Length values — Such as 500px, 3.5em, 20rem, 80ch.
• Percentage values — Such as 75%, relative to the containing block's width.
• Keyword values — max-content, min-content, fit-content, or fit-content(<length>).
• Global values — inherit, initial, revert, unset.

Examples

❌ Incorrect: using auto with max-width

<div style="max-width: auto;">

This container has an invalid max-width value.

</div>

This triggers the validation error because auto is not a valid max-width value.

✅ Fixed: using none to remove the constraint

If you want no maximum width limit (the most likely intent when writing auto), use none:

<div style="max-width: none;">

This container has no maximum width constraint.

</div>

✅ Fixed: using a specific length or percentage

If you want to cap the element's width at a specific size:

<div style="max-width: 600px;">

This container will not grow beyond 600 pixels.

</div>

<div style="max-width: 80%;">

This container will not exceed 80% of its parent's width.

</div>

✅ Fixed: using intrinsic sizing keywords

If you want the element's maximum width to be based on its content:

<div style="max-width: max-content;">

This container's max width is determined by its content.

</div>

A max-width declaration subtracts a length from the none keyword, and a keyword can't take part in arithmetic.

none means the element has no maximum width, which leaves nothing to subtract 20 pixels from. CSS identifiers can contain hyphens and digits, so the browser reads none-20px as one unknown keyword and drops the declaration. The element then takes its max-width from an earlier rule, or has no limit at all. Adding spaces doesn't help: none - 20px is a parse error, and calc(none - 20px) fails too, because calc() only works with numeric values such as lengths and percentages.

A value like this is usually the output of a preprocessor. In Sass, $max-width - 20px compiles to none-20px when $max-width is none. To Sass, none is a string, and its - operator joins a string and another value with a hyphen instead of subtracting.

Work out which width you meant. To keep the element 20 pixels narrower than its container, use calc(100% - 20px). If you didn't want a limit, write none on its own. In a Sass mixin or function, only subtract from the variable when it holds a length, and output none unchanged otherwise.

Invalid example

<div style="max-width: none-20px;">

<p>This panel was meant to stay 20 pixels narrower than its container.</p>

</div>

Valid example

<div style="max-width: calc(100% - 20px);">

<p>This panel stays 20 pixels narrower than its container.</p>

</div>

A max-width declaration has the unit px with no number in front of it, so the browser can't read it as a length.

A CSS length is a number followed by a unit, written together: 600px, 40rem, 75ch. The unit alone means nothing. Browsers drop the invalid declaration, so the element falls back to max-width: none and can grow wider than you intended.

The cause is usually a template that prints a number variable right before a hard-coded px. When the variable is empty, the output is max-width: px;. Make sure the variable always holds a number, or leave the declaration out when there's no value. If you want no limit at all, use none.

The number and the unit can't be separated by a space either. max-width: 600 px; triggers a different validator error, "Too many values or values are not recognized".

Invalid example

<div style="max-width: px;">

<p>This text block has no width limit.</p>

</div>

Valid example

<div style="max-width: 600px;">

<p>This text block stops growing at 600 pixels.</p>

</div>

A max-width declaration holds a value the property doesn't accept, often the word undefined printed by a script or template in place of a missing value.

JavaScript turns a missing value into the text undefined when it builds a string, so "max-width: " + options.maxWidth produces max-width: undefined. Appending a unit gives undefinedpx, arithmetic on a missing number gives NaNpx, and a null variable prints null. The validator quotes whatever ended up in the CSS, and it reports made-up keywords such as full with the same message.

A browser that can't parse the value drops the declaration. The element keeps the max-width from an earlier rule, or has no limit at all, so an image or text block meant to stay narrow can stretch to the full width of its container.

Fix the code that generates the value. Give the variable a default, for example options.maxWidth ?? "100%", or leave the declaration out when there's no value. The property accepts none (its initial value, meaning no limit), lengths such as 600px or 40rem, percentages of the containing block's width, the keywords min-content, max-content and fit-content, the fit-content() function, calc() expressions, and global keywords such as inherit. A number with no unit, such as 600, gets a different validator message asking for a unit.

Invalid example

<img src="harbor.jpg" alt="Fishing boats moored in the harbor" width="1200" height="800" style="max-width: undefined;">

Valid example

<img src="harbor.jpg" alt="Fishing boats moored in the harbor" width="1200" height="800" style="max-width: 100%;">