Debugging Flexbox Layouts
The flexbox gotchas that cause most layout bugs - min-width: auto, flex-shrink, and alignment - and how to debug them with DevTools.
7 min read - Updated 2026-06-15
Use this guide as a compact release reference, then validate the same breakpoints in Sizzy with synchronized devices and screenshot evidence.
The min-width: auto trap
The single most common flexbox bug is content overflowing a flex item that should shrink. By default flex items have min-width: auto, which refuses to shrink below their content size - so a long string or wide child blows out the layout. Setting min-width: 0 (or overflow on the item) lets it shrink as intended. This one rule resolves a huge share of flex overflow bugs.
Flex items default to min-width: auto and won't shrink
Long text or wide children cause overflow
Set min-width: 0 to allow shrinking
Add overflow: hidden when truncation is desired
Understand grow, shrink, and basis
Most flex confusion comes from the flex shorthand. flex-grow distributes extra space, flex-shrink removes space when cramped, and flex-basis is the starting size before those apply. flex: 1 means grow and shrink from a zero basis; flex: 0 0 auto means don't grow or shrink. Reading the shorthand correctly explains most unexpected sizing.
flex-grow distributes leftover space
flex-shrink removes space when there isn't enough
flex-basis is the size before grow/shrink apply
flex: 1 vs flex: 0 0 auto behave very differently
Use the flex overlay across breakpoints
DevTools' flex overlay shows main and cross axes, alignment, and free space - invaluable for understanding why items sit where they do. Then check the flex container across breakpoints, since flex-wrap and alignment behave differently as width changes. Sizzy shows the layout on multiple widths at once so you can see exactly where items wrap or misalign.
Enable the flex overlay to see axes and free space
Check align-items and justify-content interactions
Watch flex-wrap behavior as width changes
Compare the container across breakpoints side by side
Release checklist
Flex items that overflow have min-width: 0 set.
The flex shorthand values are understood, not copied blindly.
Wrap and alignment are checked across breakpoints.
The DevTools flex overlay is used to diagnose alignment.
Frequently asked questions
Why is my flexbox content overflowing?
Flex items default to min-width: auto, which prevents them from shrinking below their content size. Set min-width: 0 (and overflow: hidden if you want truncation) on the item so it can shrink within the container.
What does flex: 1 actually mean?
flex: 1 is shorthand for flex-grow: 1, flex-shrink: 1, flex-basis: 0%, meaning the item grows and shrinks to share available space from a zero starting size. It's different from flex: 0 0 auto, which neither grows nor shrinks.
How do I debug flexbox alignment?
Use the DevTools flex overlay to visualize the main and cross axes, free space, and alignment. Then check the layout across breakpoints, since wrap and alignment behavior changes with width.
Related guides
Benji
Your life OS
The companion app that keeps every area of your world in sync.
Zero to Shipped
Ship products, not side projects
The ultimate Next.js boilerplate for building and launching real products.
DMX
Mindful Twitter/X
The intentional X client for macOS. Reclaim your attention span.
Sotto
Voice-to-text for macOS
Speak naturally. Type instantly. 100% local & private.
Passlock
Password manager with willpower
Lock passwords with time delays, word challenges, or hand the keys to someone you trust.
Glink
Changelogs that slap
Beautiful changelogs and roadmaps for your product.
JoinRepo
GitHub access control
Monetize your GitHub repositories with ease.
Tubely
YouTube Studio for Mac
Manage multiple YouTube channels in one native app.
JustWrite
Distraction-free writing
A minimal writing app that helps you focus on what matters.