How to Fix Broken Layout on Shopify (Step-by-Step, 2025)
Seeing overlapping sections, stretched images, or a collapsed header/footer? This guide walks you through a safe, repeatable workflow to diagnose, fix, and prevent broken layouts on Shopify.
1 Quick Diagnosis Checklist
- What changed right before it broke? (theme update, app install, custom code, metafields)
- Does it break everywhere or only specific templates (e.g., product.json, collection.json)?
- Is it mobile-only or also desktop?
- Are there console errors or blocked resources (CSP, 404, 403)?
- Does disabling recent apps/embeds restore the layout?
2 Safe Staging: Duplicate Your Theme
Online Store → Themes → … → Duplicate.
Work on the copy (staging) to avoid impacting customers. Rename it clearly, e.g., ThemeName — Staging FIX 2025-MM-DD.
3 Clear Cache & Reproduce the Bug
- Hard refresh (Cmd/Ctrl + Shift + R).
- Test incognito and a second browser.
- If using a CDN/edge cache app, purge the cache for the affected pages.
4 Check the Console (JS errors) & Network
Open Chrome DevTools → Console:
- Look for red errors (e.g., TypeError, missing files).
- Network tab: ensure CSS/JS files aren’t blocked (CSP) or 404.
If a core JS fails early, CSS classes may never toggle → broken layout (e.g., sticky header never initialized).
5 Temporarily Disable App Embeds & App Blocks
Theme Editor → App embeds (right panel) → toggle OFF non-essentials.
Remove App blocks from the affected templates.
If the layout returns → isolate the exact app block/embed causing it.
6 Roll Back Recent Code Changes
Code Editor → … → Older versions (per file) to revert recent edits.
Common culprits:
- theme.liquid (moved <script> or <link> order)
- layout/theme.liquid or sections/header.liquid
- assets/theme.css / base.css (overrides)
- Recently merged snippets (snippets/*.liquid)
7 Validate JSON Templates & Section Schema
Open the broken template (e.g., templates/product.json) and ensure:
- Valid JSON (commas, braces)
- Section type exists in /sections
- Section schema {% schema %}{...}{% endschema %} is valid
Invalid schema or missing section files often crash the visual builder and can break front-end layout.
8 CSS: Containers, Grids, Breakpoints (with fixes)
Symptoms: content spans full width, columns stack incorrectly, huge whitespace, or overflow.
Quick fixes to try (add near the end of your main CSS to override safely):
|
/* 1) Contain everything to the theme's max width */
.container, .page-width, .shopify-section { box-sizing: border-box; margin-left: auto; margin-right: auto; max-width: var(--page-width, 1200px); padding-left: clamp(12px, 3vw, 24px); padding-right: clamp(12px, 3vw, 24px); } /* 2) Reset universal sizing */ *, *::before, *::after { box-sizing: inherit; } /* 3) Prevent accidental overflow that pushes layout */ img, video { max-width: 100%; height: auto; display: block; } .section, .grid, .grid--2-col, .grid--3-col { overflow: hidden; } /* 4) Grid fallback if classes were removed */ .grid { display: grid; grid-template-columns: repeat(12, 1fr); gap: var(--grid-gap, 16px); } /* 5) Mobile-first breakpoints (adjust to your theme scale) */ @media (min-width: 768px) { .md\:col-span-6 { grid-column: span 6 / span 6; } .md\:col-span-12 { grid-column: span 12 / span 12; } } |
9 Images & Aspect Ratios (with fixes)
Symptoms: stretched cards, jumping layout, uneven product tiles.
Fix with CSS aspect-ratio and object fit:
|
.product-card__media, .collection-card__media, .blog-card__media {
aspect-ratio: var(--card-ratio, 1 / 1); overflow: hidden; } .product-card__media img, .collection-card__media img, .blog-card__media img { width: 100%; height: 100%; object-fit: cover; object-position: center; } |
If your theme uses image wrappers, ensure Liquid sets a consistent ratio, e.g., square, portrait, or landscape.
10 Liquid Guards for Missing Data (with fixes)
Symptoms: sections collapse when a metafield or setting is missing.
Guard against null/blank:
|
{% if product.metafields.custom.size_guide != blank %} <a href="{{ product.metafields.custom.size_guide }}">Size guide</a> {% endif %} |
Fallback content for headings/cta:
| <h2>{{ section.settings.heading | default: 'Featured Collection' }}</h2> |
11 Script Order & Duplicate Libraries
-
Load foundational libraries before scripts that depend on them.
-
Remove duplicate jQuery or framework versions.
-
Keep third-party widgets after core theme scripts to avoid early failures.
12 Theme App Extensions vs. Hard-coded Snippets
Prefer Theme app extensions (App blocks/embeds) over manually pasted <script> tags/snippets. They’re easier to isolate/disable and less likely to break layouts during updates.
13 Locale/RTL & Font/Icon Shifts
-
Test each locale. A missing translation key can break headings/sections.
-
For RTL, ensure containers flip correctly (direction: rtl; + logical properties).
-
Validate icon fonts/variable fonts load; a 404 font can distort spacing.
14 Performance Scripts (lazyload/minify) Collisions
Two different lazy-loaders or aggressive minifiers can reorder scripts and break hydration. If you turned on:
-
App-based minify/defer + theme-level optimize + CDN optimize → pick one.
-
Disable extra optimizers and re-test.
15 Final Pre-Publish Checklist & Monitoring
- ✅ No console errors on key templates (Home, PDP, Collection, Cart/Drawer, Checkout Extensibility pages).
- ✅ Mobile & desktop breakpoints OK; header, nav, footer stable.
- ✅ App blocks/embeds re-enabled selectively and tested.
- ✅ PageSpeed/Lighthouse run shows consistent LCP/CLS/INP.
- ✅ Publish the fixed staging theme.
- ✅ Monitor GA4 & error logs for 24–72 hours.
FAQ
Why did my layout break after a theme update?
Updated CSS/JS or section schema may conflict with custom code or apps. Always duplicate your theme and test changes on staging first.
An app broke my layout—what now?
Disable the app embed/block. If fixed, contact the app dev with your console/network logs. Consider moving the feature to a native theme section.
Can I just “undo” everything?
Use per-file version history in the code editor to roll back targeted changes. Keep a GitHub-connected theme for stronger version control.
How do I stop this from happening again?
Adopt a staging → test → publish workflow, maintain a short list of allowed optimizers (one lazy-loader, one minifier), and document customizations.
