Flexbox with Different Defaults

"Point of view is worth 80 IQ points." — Alan Kay, Creative Think (1982)

You already know flexbox. That is the problem.

React Native's layout engine is Yoga, a C++ implementation of the flexbox algorithm, and it is a good one — the same rules about main and cross axes, the same justifyContent and alignItems, the same growing and shrinking of items along a line. Nothing you learned about flexbox on the web is wrong here.

What is different is where it starts. A handful of properties have different initial values, and because defaults are the values you never write down, the differences are invisible in the code and obvious on the screen. You write the same JSX you would have written in HTML, and the result is rotated ninety degrees, or overflowing its container, or refusing to fill the space you meant it to fill.

The good news is that the list is short and Yoga will tell you what is on it, because Yoga has a switch for being a browser.

Yoga will tell you what it changed

Start with the primary source, because it is unusually direct. Yoga's Node class has a method that exists solely to undo the differences:

void useWebDefaults() {
  style_.setFlexDirection(FlexDirection::Row);
  style_.setAlignContent(Align::Stretch);
}

Two lines. Plus one constant elsewhere in Style.h:

static constexpr float DefaultFlexShrink = 0.0f;
static constexpr float WebDefaultFlexShrink = 1.0f;

So by Yoga's own accounting, becoming a browser takes exactly three changes: flexDirection, alignContent, and flexShrink. Everything else in the algorithm is already the same, and the flag is not even switchable after the fact — setConfig asserts that UseWebDefaults may not be changed after constructing a Node.

React Native never calls it. I checked the renderer for setUseWebDefaults and there is no call site, which is why the differences below are permanent rather than configurable.

Here is the whole difference, as data.

The last two deserve a sentence each before we move on. boxSizing defaults to border-box, so a View with width: 100, padding: 10 and borderWidth: 5 is a hundred points wide and has seventy points of content — I measured that against Yoga directly and got 70. Web developers have been writing box-sizing: border-box as the first rule of every stylesheet for fifteen years; React Native simply starts there. And there is no position: static: the values are relative and absolute, relative is the default, and every view is therefore already a positioning context for its absolute children.

Column, not row

The most visible difference is the first one, and it has a good reason behind it.

The first frame is what a browser would have given you for display: flex with flex-direction: column written explicitly. The second is what a browser gives you for free.

Two consequences follow from the flip, and they are the ones that trip people up in the first week. justifyContent controls the vertical distribution by default, and alignItems controls the horizontal one, which is the reverse of the web reflex. And alignItems: "stretch" — a default in both systems — now stretches children across the width rather than the height, which is why a View with no width fills its parent horizontally without you asking. That is usually what you wanted, and it is worth knowing you did not ask for it.

The reason is the shape of the device. A phone screen is roughly twice as tall as it is wide, and almost every screen in every app is a vertical stack: a header, some content, a footer. Choosing column means the common case needs no property at all, and the horizontal case — a row of chips, an icon next to a label — is where you write something down.

Nothing shrinks unless you ask

This is the difference that produces the bug reports, because it does not look like a layout choice. It looks like the layout is broken.

In CSS, flex-shrink defaults to 1. Items in a flex line that do not fit are shrunk proportionally until they do, which is why a row of fixed-width boxes in a narrow container squeezes rather than spills. In Yoga, flex-shrink defaults to 0. Nothing shrinks. Items keep their size and overflow the container.

I measured it: two children with width: 250 in a row 300 wide, laid out by Yoga 3.2.1, computed to [250, 250]. A browser would give [150, 150].

The second frame is not a fix so much as an opt-in. And the opt-in is worth understanding rather than pasting everywhere, because there is a reason for the default: on a phone, silently shrinking a control below its designed size is often worse than overflowing, since a squeezed button becomes untappable and squeezed text becomes unreadable. Overflow is at least visible. Shrinkage is a quiet degradation you may not notice until a user with a long name or a large text setting sends a screenshot.

The practical rule is that flexShrink: 1 belongs on the element that should absorb the pressure — usually the flexible middle of a row — and not on the fixed things around it. A row with an avatar, a name and a timestamp wants the name to shrink and the other two to keep their size, which is one flexShrink: 1 rather than three.

What flex: 1 actually means

Now the finding that sent me to a second source, because it contradicts React Native's own documentation.

flex is a shorthand, and Yoga expands it in three separate methods rather than one. Reading them in order:

float Node::resolveFlexGrow() const {
  if (owner_ == nullptr) return 0.0;                       // root nodes never grow
  if (style_.flexGrow().isDefined()) return style_.flexGrow().unwrap();
  if (style_.flex().isDefined() && style_.flex().unwrap() > 0.0f) return style_.flex().unwrap();
  return Style::DefaultFlexGrow;                           // 0
}

Style::SizeLength Node::processFlexBasis() const {
  Style::SizeLength flexBasis = style_.flexBasis();
  if (!flexBasis.isAuto() && !flexBasis.isUndefined()) return flexBasis;
  if (style_.flex().isDefined() && style_.flex().unwrap() > 0.0f) {
    return config_->useWebDefaults() ? StyleSizeLength::ofAuto() : StyleSizeLength::points(0);
  }
  return StyleSizeLength::ofAuto();
}

float Node::resolveFlexShrink() const {
  if (owner_ == nullptr) return 0.0;
  if (style_.flexShrink().isDefined()) return style_.flexShrink().unwrap();
  if (!config_->useWebDefaults() && style_.flex().isDefined() && style_.flex().unwrap() < 0.0f) {
    return -style_.flex().unwrap();
  }
  return config_->useWebDefaults() ? Style::WebDefaultFlexShrink : Style::DefaultFlexShrink;
}

Read the third one carefully. With web defaults off, a positive flex never reaches the shrink branch — that branch only fires for a negative flex — so the method falls through to DefaultFlexShrink, which is 0.

Which means flex: 1 in React Native is flexGrow: 1, flexShrink: 0, flexBasis: 0. The documentation says flexShrink: 1.

Practically this matters less often than it sounds, because flex: 1 also sets flexBasis: 0, and an item whose basis is zero has nothing to shrink from — it is sized entirely by growing. You notice the difference only when a basis or a size is also in play. But when you do notice it, nothing else explains it, and the documentation will actively mislead you.

alignContent, and what wrapping does

The third switchable difference is the one people meet least often, because it only applies when a container wraps.

alignContent distributes the lines of a wrapped flex container along the cross axis, and CSS starts it at stretch while Yoga starts it at flex-start. So in a browser, wrapped rows spread out to fill the container's height; in React Native they pack against the top and leave the remainder empty.

Measured on the same tree — four boxes of 120 by 40 wrapping in a 200 by 200 container — the tops come out as [0, 40, 80, 120] with Yoga's default and [0, 50, 100, 150] with alignContent: "stretch".

The left frame packs its four rows against the top with a gap at the bottom. The right frame spreads them. Neither is wrong; the left is simply the one you get without asking, and if you have ever wondered why a wrapped grid in React Native does not fill its container the way the same code did on the web, this is the entire reason.

What is simply not there

Finally, the absences, because knowing them saves you searching.

There is no display: block or display: inline. display takes flex and none, and every View is a flex container — there is no non-flex layout mode to fall back to. There is no float, no CSS Grid, no multi-column layout. There are no media queries, because there is no stylesheet to attach them to; the equivalent is reading useWindowDimensions and branching in JavaScript, which is the next chapter but one. There is no calc(), and percentages are supported for sizes, margins, padding and flexBasis but not everywhere.

What is there and is easy to miss: gap, rowGap and columnGap work, and are the right way to space children rather than margins on every child. aspectRatio works as a first-class style property — Yoga had it years before CSS did — and a width of 200 with aspectRatio: 16 / 9 computes to a height of 113. And margin: "auto" works for centring and pushing along the main axis: an item 50 wide with marginLeft: "auto" in a 300-wide row lands at 250, which is the idiom for "push this to the end" without a spacer view.

Common Mistakes

1. Assuming a row. flexDirection defaults to column, so children stack vertically until you say otherwise.
2. Reaching for justifyContent to centre horizontally. In a column it centres vertically; alignItems is the horizontal one.
3. Expecting items to shrink. flexShrink defaults to 0, so a row that does not fit overflows rather than squeezing.
4. Believing flex: 1 sets flexShrink: 1. It does not — the engine resolves it to 0, whatever the documentation says.
5. Putting flexShrink: 1 on everything in a row. Put it on the element that should absorb the pressure, not the fixed ones around it.
6. Expecting overflow to be clipped. overflow defaults to visible, so children are drawn outside their parent unless you set hidden.
7. Adding padding to a fixed width and expecting the box to grow. Sizing is border-box, so the padding comes out of the width.
8. Looking for position: static. There is none; every view is relative and therefore already a containing block.
9. Wondering why a wrapped grid does not fill its height. alignContent starts at flex-start, not stretch.
10. Spacing children with a margin on each. gap exists and does not produce a stray margin on the last child.

Interview Corner

Hands-on

Summary

• Yoga is a real flexbox implementation with different initial values, so the algorithm you know applies and the starting point does not.
• Node::useWebDefaults() is two lines plus one constant, so by Yoga's own accounting exactly three defaults separate it from a browser.
• React Native never calls it, which makes every difference in this chapter deliberate and permanent rather than configurable.
• flexDirection defaults to column, which swaps which axis justifyContent and alignItems control.
• flexShrink defaults to 0, so a row that does not fit overflows instead of squeezing — the source of most first-week layout bugs.
• flex: 1 resolves to flexGrow: 1, flexShrink: 0, flexBasis: 0, contradicting React Native's documentation, verified against yoga-layout 3.2.1.
• alignContent defaults to flex-start, so wrapped lines pack at the start rather than stretching to fill.
• Sizing is border-box and there is no position: static, neither of which has a browser-compatibility mode.
• overflow defaults to visible, so an overflowing row is drawn outside its parent rather than clipped.
• gap, aspectRatio and margin: "auto" all work, and are usually better than the workarounds people reach for first.

In the next chapter, StyleSheet Is Not CSS, we look at the other half of the resemblance — an API that borrows CSS's property names and almost none of its semantics, with no cascade, no selectors, no inheritance beyond the one case from Part II, and a create function whose actual job is not what its name suggests.