Common HTML and CSS Problems and How to Fix Them

cover

Most HTML and CSS problems are not new. The same dozen issues have filled help forums for twenty years: an element that will not center, a layout that breaks on mobile, a style that refuses to apply. The tools have improved, so the fixes are simpler than they used to be. This guide goes through the problems we see most often, why each one happens, and the modern way to fix it.

If you are still learning layout from scratch, start with How to Learn CSS Layout: Flexbox, Grid and Beyond and come back here when something breaks.

Before you debug anything

Three habits solve a surprising number of problems before you even look at the CSS:

  1. Validate the HTML. An unclosed <div> or a missing quote can shift everything after it. Run the page through the W3C validator and fix the errors first.
  2. Open the browser's developer tools. Right-click the element, choose Inspect, and look at the Styles and Computed panels. They show which rules apply, which are crossed out, and where each one comes from.
  3. Reduce the problem. Copy the broken part into an empty page or a code playground. If it works there, the problem is somewhere else in your CSS. If it still breaks, you now have a small example you can share when asking for help.

1. "My style isn't being applied"

This is the most common question of all, and it almost always comes down to one of four causes:

  • Specificity. A more specific selector wins. #header .nav a beats .nav a no matter which comes later in the file. In developer tools, a crossed-out rule tells you something else is winning.
  • Order. When two selectors are equally specific, the later one wins. Check that your stylesheet loads after any framework or theme CSS.
  • A typo or invalid value. One missing semicolon can cancel the next declaration. Developer tools mark invalid properties with a warning icon.
  • Caching. The browser may still be using an old version of your stylesheet. Do a hard refresh, or add a version number to the file name when you deploy.

Avoid fixing specificity fights with !important. It works once, then the next fix needs another !important. Lower the specificity of the original rule instead, or use @layer to control which group of styles wins.

2. Centering things

Centering used to need tricks. Today there are two reliable answers:

/* Center one child horizontally and vertically */
.parent {
  display: grid;
  place-items: center;
}

/* Center a row of items */
.row {
  display: flex;
  justify-content: center;
  align-items: center;
}

For a block of text or a fixed-width container, margin-inline: auto on the element still does the job. If vertical centering does nothing, check that the parent actually has a height. A parent that is only as tall as its content has no extra space to center in.

3. The layout breaks on mobile

A page that looks fine on a laptop and overflows on a phone usually has one of these problems:

  • The viewport meta tag is missing. Without <meta name="viewport" content="width=device-width, initial-scale=1">, phones render the page at desktop width and shrink it.
  • Fixed widths. An element with width: 1200px forces horizontal scrolling. Use max-width with a percentage, or let Flexbox and Grid size things.
  • Images and videos without limits. Add img, video { max-width: 100%; height: auto; } to your base styles.
  • Long words and URLs. A long link can push a column wider than the screen. overflow-wrap: anywhere on text containers fixes it.

To find the element that causes horizontal scrolling, add * { outline: 1px solid red; } temporarily and look for the box that sticks out.

4. Margins that collapse or disappear

When two vertical margins touch, the browser uses only the larger one. A heading with margin-bottom: 20px above a paragraph with margin-top: 30px gives a 30px gap, not 50px. A child's top margin can also "leak" out of its parent and push the parent down instead.

The simplest fix is a consistent rule: set margins in one direction only, usually margin-bottom. Inside Flexbox and Grid containers margins do not collapse at all, and the gap property is usually a better way to space items there.

5. Floats and clearing in old code

If you maintain an older site, you will still meet float-based layouts. The classic symptom is a parent with zero height, because floated children do not take up space. Adding display: flow-root to the parent fixes it without the old clearfix hacks. For new layouts, use Flexbox or Grid and keep floats for what they were designed for: wrapping text around an image.

6. z-index doesn't work

Setting z-index: 9999 and seeing no change is frustrating. Two things to check:

  1. Positioning. In normal flow, z-index needs position set to something other than static. Flex and grid items are an exception and accept it directly.
  2. Stacking contexts. A parent with transform, opacity below 1, filter or its own z-index creates a new stacking context. Children can never escape it, whatever their z-index. Find that parent in developer tools and move the element, or adjust the parent instead.

Dropdown menus hidden behind other content are the most common case. Our guide to building navigation menus with modern CSS covers this in more detail.

7. Images look stretched, blurry or leave gaps

  • Stretched: set only one dimension, or use object-fit: cover when the image must fill a fixed box.
  • Blurry: the file is smaller than the space it fills. Provide a larger version with srcset for high-density screens.
  • A small gap under images: images are inline by default and sit on the text baseline. display: block removes the gap.
  • Layout jumping while images load: always include width and height attributes, so the browser can reserve the space.

For choosing formats and keeping files small, see Image Editing for the Web.

8. Fonts that don't load or look different

If a web font falls back to Times or Arial, check the file path in your @font-face rule, the network panel for 404 errors, and CORS headers when fonts come from another domain. Add font-display: swap so text shows immediately in a fallback font. When text looks bolder or lighter than expected, the weight you asked for may not exist in the files you loaded, so the browser fakes it.

9. Forms that look different in every browser

Form controls come with browser default styles. Start by setting font: inherit on inputs, buttons and selects, so they match your text. Use accent-color to color checkboxes and radio buttons without rebuilding them. Keep a visible focus style: removing the outline makes the form unusable for keyboard users.

10. HTML mistakes that cause CSS problems

  • Block elements inside inline ones, like a <div> inside a <span> or a <p>. Browsers repair this in unexpected ways.
  • Duplicate IDs. CSS may style both, but JavaScript and anchors will only find the first.
  • Using headings for size instead of structure. Pick the heading level for the outline of the page, then style it.
  • Tables for layout. They make responsive design very hard and confuse screen readers.

A debugging checklist

  1. Validate the HTML and fix errors.
  2. Inspect the element and look for crossed-out rules.
  3. Check the Computed panel for the final value and where it comes from.
  4. Test in a second browser to see whether the problem is browser-specific.
  5. Reduce the problem to the smallest example that still breaks.
  6. Search for the exact symptom, then ask for help with your small example attached.

Most layout bugs are found in the first three steps. The rest become much easier to solve once you can show someone else a ten-line example instead of a whole website. And when the problem is not code but whether the design works, our guide on getting useful feedback on your website design is the next step.

Related reading: JavaScript for Web Designers · How to Learn CSS Layout · What Makes a Good Website?

Comments