CSS Flexbox Not Working — Diagnosis and Fix Guide

Flexbox failures share a single pattern: a property is applied to the wrong element, or a default value silently overrides your intent. The flex model is a parent-child contract. When you write display: flex, you are declaring that this element's direct children will be laid out as flex items. Properties like justify-content, align-items, flex-direction, and flex-wrap all live on the parent and control how the container arranges its children. Properties like flex-grow, flex-shrink, flex-basis, align-self, and order live on the children and describe how each item behaves within the container.

The most disruptive default is min-width: auto on flex items. In normal block layout, a div shrinks to its container's width freely. In a flex container, each item defaults to min-width: auto — meaning it will never shrink narrower than its content. This is the correct default for most text-heavy layouts, but it causes overflow when you expect columns to shrink to fit the container. Setting min-width: 0 on the flex child overrides this default and allows the flex algorithm to shrink the item below its content width.

flex-wrap: nowrap is the other significant default. All flex items stay on a single line by default, and if they cannot fit, they overflow the container. Most developers expect items to wrap when the container is narrow. Adding flex-wrap: wrap to the container gives items permission to move to the next line. combine it with a min-width or flex-basis on the children to control where wrapping occurs.

flex-basis overrides width in a flex context. If you set width: 50% on a flex item and also have flex-basis: auto in a shorthand like flex: 1, the flex-basis value wins. Always check the computed flex-basis in DevTools when a width appears to have no effect in a flex row.

Select the parent container in Chrome or Firefox DevTools Elements panel. A colored flex badge appears next to its tag. Click the badge to open the Flexbox overlay, which draws the main axis, cross axis, and free space directly on the page. This immediately shows whether items are overflowing, whether there is free space that alignment should be using, and whether items are on one or multiple lines.

In the Computed tab, find the element and look at the resolved values for display, flex-direction, flex-wrap, justify-content, and align-items. A value of nowrap in the computed display when you expected wrapping is the instant indicator of why content overflows. A computed height of 0 explains why align-items: center has no vertical effect.

For flex items, check the computed flex-basis, flex-grow, flex-shrink, and min-width. If min-width shows auto and a large resolved value, that is the item that is preventing the column from shrinking. Temporarily set min-width: 0 in the Styles panel and observe whether the layout shifts to confirm the diagnosis.

The Layout pane in Chrome DevTools has a Flexbox section that lists all flex containers on the page. Enable overlay badges to highlight them. This is especially useful in React or Vue applications where the container may be several DOM levels above the visible component, making it hard to find which element actually has display: flex.

Chrome's Flexbox inspector also shows a purple badge specifically on elements with display: flex or display: inline-flex, distinguishing flex containers from grid containers which use a green badge. When a flex item has align-self set to a value that overrides the container's align-items, the overlay draws a dotted line indicating the override is active for that specific item. This makes it straightforward to identify which child is breaking the cross-axis alignment pattern.

If items are stacking vertically when they should be in a row, verify display: flex is on the parent. Check the computed flex-direction — it should be row for horizontal layout. If it is column (set explicitly or inherited from a theme), change it or reorganize your CSS. Browser stylesheets do not add flex-direction to common elements, so this is nearly always a CSS rule in your own code.

If alignment properties have no effect, the container has no height. For horizontal containers with align-items, add height: 300px or min-height: 100% to the container. For full-viewport centering, use min-height: 100vh. For a container inside a fixed-height parent, add height: 100% and ensure the parent chain has defined heights all the way up.

If items overflow instead of wrapping, add flex-wrap: wrap to the container. Then control each item's minimum width with flex-basis: 250px or min-width: 200px — this dictates when wrapping occurs. Using flex: 1 1 250px (grow, shrink, basis) on children is the cleanest way to create a responsive wrapping layout.

If a specific item refuses to shrink, add min-width: 0 to that item. Also consider adding overflow: hidden or overflow: auto if the item contains text that would be clipped. For text specifically, add overflow-wrap: break-word to prevent long unbreakable strings from forcing the item wide.

For individual items that need different cross-axis positioning from the rest of the group, use align-self on that specific child. align-self accepts the same values as align-items — flex-start, flex-end, center, stretch, baseline — and overrides the container's align-items rule for just that element. This is cleaner than splitting items into separate flex containers to achieve the exception. Similarly, the order property on a flex child changes its visual position within the row without altering the DOM order, which is useful for responsive reordering without JavaScript.

Safari on iOS has historically had stricter flex behavior than Chrome and Firefox. One well-known issue is that Safari does not always respect flex: 1 on a direct child of a flex column container unless the container has an explicit height. The workaround is to set height: 0 and flex-grow: 1 separately, which forces Safari to distribute height correctly through the flex algorithm.

On mobile devices, the browser chrome (address bar and navigation bar) changes the effective viewport height as the user scrolls. A flex container with height: 100vh may be cut off or show unexpected empty space. Use height: 100dvh (dynamic viewport height) in browsers that support it — Chrome 108+, Safari 15.4+, Firefox 101+. For older mobile browsers, add a JavaScript resize listener or use the VisualViewport API to set the height dynamically.

Flex items with aspect-ratio set may not behave as expected when the flex container changes size. The aspect-ratio property interacts with flex-basis and the flex algorithm in ways that differ between browsers. If an image or video inside a flex item is unexpectedly tall or wide, check whether aspect-ratio combined with a percentage flex-basis is causing unexpected dimension calculations.

Internet Explorer 11 supports an early version of Flexbox but uses non-standard syntax and has numerous bugs. flex: 1 must be written as flex: 1 1 auto for IE 11 compatibility. min-height on flex containers inside a flex column works differently. align-items: stretch is the only reliably consistent behavior across IE 11 and modern browsers. Most production codebases no longer target IE 11, but if you must, use Autoprefixer and test every layout manually.

Using display: inline-flex when you mean display: flex is a subtle mistake. inline-flex creates a flex container that behaves as an inline element in its parent context — useful for a flex button inside a paragraph, but confusing when the intent was a block-level flex row. The items inside are still flex items, but the container itself does not expand to the full width of its parent.

Setting align-items on the container and expecting it to control alignment inside flex children is another common error. align-items controls how children are positioned on the cross axis within the container. If you want to center content within a flex child, that child needs its own display: flex and alignment properties. Flex containers do not cascade alignment rules into their children.

Writing flex: 1 and expecting it to work identically in all browsers is risky. The shorthand expands to flex-grow: 1; flex-shrink: 1; flex-basis: 0. The flex-basis: 0 means the item starts with zero size and grows to fill space. This is often what you want, but it can cause text to disappear if the container is too narrow and shrinking is not constrained. Use flex: 1 1 auto or flex: 1 1 min-content when content must not shrink below a readable size.

Using percentage heights on flex children when the container has no explicit height is a reliable way to break a layout. Percentage heights resolve against the parent's computed height. If the parent has height: auto, percentage heights on children resolve to auto as well — they do not take a percentage of the content height. Add an explicit height to the flex container or use min-height on the children.

Build flex layouts from the container inward. Start by deciding what the container needs — flex-direction, flex-wrap, gap, alignment — before touching the children. This sequencing prevents the most common mistake of writing child properties before establishing the flex context.

Always include flex-wrap: wrap on containers that hold multiple items unless you explicitly want items to stay on one line and overflow is acceptable (such as a horizontally scrollable strip). Defaulting to wrap makes layouts resilient to varying content lengths and small screens.

Use the gap property instead of margin on flex children for spacing. gap: 1rem creates equal gutters between all items without the margin-collapse and negative-margin workarounds of the old approach. gap is supported in all modern browsers including Safari 14.1+.

When you need equal-height columns, the default align-items: stretch on the flex container already produces equal-height columns without any additional properties on the children. Only override align-items if you specifically do not want equal-height columns.

Document complex flex values. flex: 0 0 260px is opaque — a comment explaining that the sidebar is fixed at 260px and does not grow or shrink makes the intent clear for future maintainers. The flex shorthand's compactness is valuable in utility CSS but benefits from a comment in component-level stylesheets.

Apply flex-shrink: 0 to any flex child that must never shrink below its flex-basis, such as an icon, avatar, or fixed-width sidebar. Without it, the flex algorithm may compress the element when space is tight, even if you set an explicit width. Pairing flex-shrink: 0 with a defined flex-basis gives the element a guaranteed minimum footprint. For text children that should truncate with an ellipsis, add min-width: 0, overflow: hidden, text-overflow: ellipsis, and white-space: nowrap — min-width: 0 is the key that allows the text container to shrink enough for the ellipsis to engage.