Skip to content

fix(transformers): resolve and cascade transform properties as browsers do - #576

Merged
danstepanov merged 17 commits into
nativewind:mainfrom
sammoore:fix/scale-percentage
Nov 18, 2026
Merged

danstepanov merged 17 commits into
nativewind:mainfrom
sammoore:fix/scale-percentage

Conversation

@sammoore

@sammoore sammoore commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Supersedes #389; reduces diff where unnecessary or orthogonal to the issue/solution, while improving the perf and passing the same tests that remain relevant:

Refactored

  • Smaller compiler.ts diff: main's variable counter kept as-is
  • Drop calculation.ts and tokens.ts
  • Only handle the longhand translate, rotate, and scale grammars that Tailwind actually uses
    • separated into a patch to accept after Nativewind v5
    • edge-case added after removal: none coming from a var() doesn't transform

Performance

The PR this replaces made elements without a transform 3-17% slower on Hermes, and with transforms 13-49% slower. This branch rectifies that: every case is faster on some level (in some niche cases 23% faster), except for var()s in transforms, at 4% slower.

  • Record transform declarations without per-render closures (or a Map)
  • Improve transform composition and operand reading perf
  • Resolve transform shorthand functions one by one
  • Compose a single transform declaration directly / avoid the cascade's per-render bookkeeping

Problem

React Native's transform validator throws on any entry it cannot take, with Transform with key of "scale" must be a number or You must specify exactly one property per transform object. #451 converts a percentage scale through scaleFactor, which closes #216. On main, these still go wrong:

  1. Entries React Native refuses.
    • A two-operand scale() or translate() resolves to a group: transform: translate(10px) compiles to [{ translateX: 10 }, [{ translateY: 0 }]], and a var() fallback holding a function nests deeper. A written translate(10px, 20px) or translate(-50%, -50%) nests its second offset the same way, so React Native throws on it even with no var() involved.
    • An unsupported function (translateZ(), scale3d(), scaleZ(), matrix()) leaves an empty group, which takes its neighbours down with it.
    • A value that is no transform reaches the validator: scaleX(var(--missing)) and scale: initial as an entry without a value, scale: unset as { scale: null }, scale(var(--s)) with --s: none as { scale: "none" }, and translate: initial as the placeholder { translate: true }.
    • An argument the compiler cannot convert compiles to an empty entry: transform: translate(10px, 1cap) reaches React Native as [{ translateX: 10 }, [{}]], rotate(1grad) as [{}], and a typed calc() such as translate(calc(1em + 5px), 5px) as [{}, [{ translateY: 5 }]].
  2. Misread operands. A var() that supplies the whole operand list is read as one operand, so translate: var(--offset) with --offset: 10px 20px leaves the placeholder and scale: var(--s) with --s: 2 3 reaches React Native as { scale: [2, 3] }. scale(2, var(--missing)) renders { scale: 2 }, where browsers make the transform none.
  3. No cascade between the transform properties. Browsers cascade each of translate, rotate, scale and transform on its own and compose them in that order (css-transforms-2 §6). Here a longhand applies after the transform property and removes its entry of the same name: rotate: 20deg beside transform: rotate(10deg) renders [{ rotate: "10deg" }, { rotateZ: "20deg" }], and translate: 10px 20px beside transform: translateX(5px) loses the translateX(5px). lightningcss also folds a longhand written beside transform into it, so translate: none after transform: rotate(5deg) in one rule keeps an earlier rule's translation.
  4. The longhands read the transform functions' grammars. translate: var(--t) with --t: 10px 20px 30px leaves the placeholder; Tailwind's 3D utilities write a third value the same way (scale-3d writes scale: var(--tw-scale-x) var(--tw-scale-y) var(--tw-scale-z)). rotate: var(--r) with --r: x 45deg reaches React Native as { rotate: ["x", "45deg"] }, which it throws on.

Solution

  • Entries. The transform shorthand spreads every level of nesting into the list, and if any item is not a single-key entry the declaration is invalid at computed-value time and the transform is none (css-variables-1 §3.1). The resolvers and the transformKeys branch of resolveValue return null for an operand they cannot use, and read an operand list a var() supplies, whole or in part. A function given more operands than it takes is invalid. An operand must be a number or a dimension, so a keyword such as none coming from a var() makes the property none rather than reaching React Native.
  • Cascade. Each of the four properties records its cascaded value per style target, !important included, and the slots compose into one transform after every rule. The compiler emits each longhand as one declaration under its own name, and carries it through the first pass unparsed, because lightningcss before fix: preserve individual transform properties parcel-bundler/lightningcss#1340 folds a parsed longhand into transform.
  • Grammars. translate and scale accept an optional z (css-transforms-2 §3), which React Native has no axis for, as Tailwind's 3D utilities write one. rotate reads a single angle, as rotate() does. Axis keywords and vectors for rotate, and none substituted from a var(), are in a separate patch credited to the original author.
  • Arguments the compiler cannot convert. The declaration is ignored with a warning, as width: 1cap already is (CSS 2.2 §4.2). parseLength, which does not compile a typed calc(), now warns for one. That applies to every property: a calc() that mixes a percentage with a length (h-[calc(100%-1rem)]), or vw/em with px, was already dropped silently on main. The warning goes through the warnings option, so "none" silences it.
  • A scale renders as the scaleX / scaleY pair on both routes, as the compiler already wrote it.
  • Built on fix: keep a list's separator when read through variables or custom properties #575. Each comma-separated argument is unwrapped through fix: keep a list's separator when read through variables or custom properties #575's argument(), and a lone var() holding a comma-separated list supplies its items as the operands, through commaListItems.

Tests

  • src/__tests__/native/transform.test.tsx covers each shape above on both routes: every unsupported, invalid and missing operand alone and beside a valid function, over an earlier rule; the longhands composed with transform in each rule order and with !important; a written two-operand translate() and translateZ(); none and a z for each longhand, and an axis keyword in either order for rotate; and an unconvertible argument. 70 of its 90 cases fail on main.
  • src/__tests__/compiler/compiler.test.tsx pins the warnings for unconvertible arguments and the ignored declarations.
  • Every expectation is what Chromium 153, Firefox 155 and WebKit 26.6 compute for the same CSS.

Known limits

  • React Native's 16-value matrix can draw scale3d(), scaleZ(), matrix(), matrix3d(), translate3d(), rotate3d() and a rotation about an oblique axis; each renders no entry here, as on main.
  • rotate: with a vector about a negative or oblique axis, the zero vector, and an axis keyword or vector substituted from a var() behave as on main; the separate patch handles them.
  • A var() list counts as operands whichever separator it uses. fix: keep a list's separator when read through variables or custom properties #575 keeps the separator, but these readers don't enforce it, which is lenient rather than a crash. Browsers read a comma-separated list only in a function and a space-separated one only in a property.
  • grad and turn angles are ignored with a warning, as on main.

YevheniiKotyrlo and others added 17 commits November 17, 2026 20:11
React Native's transform validator requires exactly one property per entry and throws
otherwise. A resolver returns a group for a two-operand scale() or translate(), the compiler
emits one for translate(10px), and an unsupported function such as scale3d() leaves an empty
one, so each reached React Native as a nested array. The transform shorthand now spreads a
group into the list, which also drops the empty one and keeps its neighbours.
A transform function or longhand whose var() leaves it no valid value reached React Native as
an entry it rejects: `scaleX(var(--missing))` and `rotate: var(--missing)` as an undefined
value, `scale(var(--s))` with `--s: none` as the string "none", and `scale: initial`,
`translate: initial` or a longhand with two missing operands as the placeholder `true`. Each
throws in the transform validator.

Browsers treat each declaration as invalid at computed-value time (css-variables-1 §3.1): a
function without a valid argument leaves no transform, and a longhand without a value is none.
A resolver now returns null for an operand it cannot use, the transform shorthand turns that
into an empty list, and a longhand that resolves to nothing removes its entries. A scale factor
is a number or nothing, and a one-operand translate() translates along x, as translate(x) is
translate(x, 0).
A var() fallback holding a translate() pair nests a level deeper than a resolver's group, and a
var() holding bare lengths (`--offset: 10px 20px; transform: var(--offset)`) resolves to
numbers rather than entries; both reached React Native's validator. The shorthand now spreads
every level, and a list with any item that is not a single-key entry is none, as browsers treat
the declaration as invalid at computed-value time.
`translate: var(--offset)` with `--offset: 10px 20px`, `transform: translate(var(--offset))`
with `--offset: 10px, 20px` and `scale: var(--s)` with `--s: 2 3` each resolve their single
var() to the whole operand list, which the resolvers read as one operand and rejected. A
missing second operand, as in `scale(2, var(--missing))`, still leaves the declaration invalid
rather than falling back to the first.
On its own, a function left without a valid argument gives the same empty
transform whether it is read as invalid or dropped. Next to a valid
translateX(5px) only the invalid reading leaves no transform, which is what
browsers compute.
…d in CSS order

translate, rotate, scale and transform each cascade on their own, and the
element's transform composes them in that order (css-transforms-2 §6). The
runtime appended a longhand to whatever transform array it found, and a later
transform replaced the longhands.

Each property now records its cascaded value per style target, and the slots
compose into one transform after every rule. The compiler emits each longhand
as one declaration under its own name, and carries it through the first pass
unparsed, because lightningcss before parcel-bundler/lightningcss#1340 folds a
parsed longhand into transform.

A transform argument the compiler cannot convert now ignores the declaration
with a warning (CSS 2.2 §4.2), as width: 1cap already does, instead of
rendering an empty entry React Native refuses. A typed calc() warns too.
The individual transform properties each have a grammar of their own
(css-transforms-2 §3): translate and scale take an optional z, and rotate
takes an axis keyword or a vector beside its angle, in either order. A
deferred one ran through the transform function of the same name, which
takes no z, no axis and no none.

Each now resolves through its own grammar on both routes. A rotation turns
about the axis its vector names, reversed about a negative axis, and the
zero vector rotates by none; the compiler and the runtime share that one
decision. React Native's rotate keys turn only about an axis, so a vector
off every axis warns and is ignored when written, and is none when
substituted. A scale along z warns.

A var() can supply part of a property's values, and they splice into the
rest. A transform function given more operands than it takes is invalid.
…outes

The compiler writes scale(2) and scale: 2 as the scaleX / scaleY pair, while
the runtime wrote the same value as one scale entry when both axes matched.
Both routes now write the pair, so one value has one shape whichever route
resolves it.
The transform cascade built a Map, a recorder object and a closure for
every calculateProps call, and a further closure for every rule, and
tested each dynamic declaration with TRANSFORM_PROPERTIES.includes(). An
element with no transform paid all of it: about 400 ns per render on
Hermes for a single color: var(--c).

A transform declaration now pushes one record onto an array, the slots
are grouped and composed only when one was recorded, and the property
test is four string compares. The cascade is unchanged: slots compose in
css-transforms-2 §6 order, a later rule replaces an earlier one, and an
!important slot replaces a normal one for the same path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
On main, `transform: translate(10px, 20px)` compiles its second offset a
level too deep, and `translateZ()` compiles to an empty entry, so React
Native's processTransform throws on both in development. The compiler
fix here covers them, but only through a var() fallback, or scale3d(),
scaleZ() and matrix(), so these render the written forms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ariable counter

The individual transform properties are unparsed in every compile, while
variables are counted only when they are inlined. Keep the counting block
as it was, named, and add a Declaration visitor that runs it and then
unparses, instead of restructuring the block around the new step.

Also leaves parseScaleValue's parameter named as on main; renaming it is
unrelated to the fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…enizing it

The first-pass workaround rebuilt a calc() from lightningcss's
calculation tree only so that the second pass could warn about it and
ignore it: React Native takes no calc(). A translate holding one now
stays parsed. Alone in its rule it reaches the same warning. Beside a
transform, lightningcss folds it into a translate3d() that the compiler
drops either way, so the rendered style is the same and only that
warning is lost. Tailwind writes its translate with var(), which is
already unparsed, so it never takes this path.

With calculation.ts gone, tokens.ts had one reader, so what it still
needs moves into individual-transforms.ts. Each component is one token,
so the space join takes tokens rather than groups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On Hermes, transforms still cost 19-44% more than on main, in the
calculate-props cascade and in the readers it calls on every render:

- composeTransforms keyed a Map by a joined path string and kept each
  slot set as an object tested with `in`. Records now carry a slot index,
  and a style target's 4 normal and 4 !important slots are an array,
  found by a scan of the targets, which is almost always one.
- The transform shorthand flattened, filtered and tested its list in
  three passes. One recursive pass now flattens it, skips undefined and
  `initial`, and stops at the first value that is not an entry.
- resolveOperands mapped then flat-mapped through closures, and the
  individual properties sliced their operands to drop a z. The operands
  are now pushed in one loop, and the pairs read a count instead of a
  copy. Destructuring is gone from the readers, since Hermes runs it
  through an iterator helper.

Output is unchanged. On Hermes, against main, ns per calculateProps
call, 5 processes per side:

  tw translate-x-4 rotate-45 scale-110  +18.7% -> -1.9%
  tw rotate-45 skew-x-6                  +5.5% -> -6.5%
  translate: 10px 20px (written)         +3.6% -> -17.3%
  transform: translate() rotate()       +39.3% -> +4.0%
  tw transform, one set                 +24.7% -> +6.9%
  transform: scale(var(--s))            +37.6% -> +7.5%
  transform: var(--t) two fns           +43.1% -> +8.7%
  translate(var(--x), var(--y))         +43.6% -> +12.0%

The cases left above main are transform functions whose output main
nests in a way React Native refuses. Rules with no transform are flat.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The grammar commit gave translate, rotate and scale their own grammars:
an optional z, a none keyword substituted from a var(), and for rotate an
axis keyword or a vector beside its angle, reversed about a negative
axis, with an oblique vector warned and ignored. It added a shared
rotationAxis() utility and a warning for a scale along z.

Tailwind needs one part of it. scale-3d and scale-z-* write a three-value
`scale: var(--tw-scale-x) var(--tw-scale-y) var(--tw-scale-z)`, as its 3D
translate utilities do for translate, so individualTranslate and
individualScale keep taking an optional z. The rest only matters for CSS
written by hand: Tailwind writes `rotate: <angle>` (rotate-x-* goes
through transform:) and writes none literally, which the compiler already
reads. So this removes individualRotate, the substituted none keyword,
rotation-axis.ts, the vector handling in parseRotate and the scale z
warning. A rotate longhand from a var() reads through rotate() again, as
`{ rotate: angle }`, which React Native treats as rotateZ.

Without the keyword handling, a none from a var() reached React Native
as { translateX: "none" } or { rotate: "none" }, which it throws on.
isTransformComponent now takes only a number or a dimension, so a
keyword makes the property none: the identity, as browsers render it.

133 Tailwind utilities and combinations render identically before and
after, and every result passes React Native's processTransform; no
hand-written case throws either. The 13 test cases for the removed
grammar, and the compiler test for its warnings, go. The removed grammar
is kept as a patch for later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
The transform shorthand resolved its argument list with resolveValue,
which maps the list into a new array and filters that into another, and
then copied the result into its list of entries. It now resolves each
function in turn and appends it, so a transform: with two functions
allocates one array instead of three. The output is unchanged.

On Hermes (list-bench, against bench), the transform: cases go from
+7–14% to −5…+3%: transform: translate(10px, 20px) rotate(45deg) +9.9%
→ −4.7%, translate(var(--x), var(--y)) +11.9% → −0.1%, transform:
var(--t) +14.0% → +3.1%, scale(var(--s)) +12.2% → +0.5%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
The list-separator fix tested that each one-token argument of a
comma-separated list is unwrapped with rotate() over three arguments,
which main read as rotateX, rotateY and rotateZ. The transform-properties
fix reads rotate() by its grammar, which takes one angle, so three
arguments are invalid and render none. translate() over two arguments
tests the same unwrapping with a function that takes them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
composeTransforms set up a group and its eight slots on every render,
even when an element has only one transform property, which is the
usual case. With one record there is nothing to compose, so resolve it
and flatten it into the target's transform directly.

Hermes list-bench against main (7-15 processes per side):
- transform: var(--t): +17% -> +4%
- translate(var(--x), var(--y)): +8% -> -1%
- Tailwind transform, one set: +4% -> -3%
- transform: scale(var(--s)): +3% -> -7%
- written transform: translate() rotate(): +1% -> -8%
- no other case moves
V8 stays 39-53% faster than main on the transform cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
@danstepanov
danstepanov merged commit 572b652 into nativewind:main Nov 18, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Animation error caused by incorrect value type

3 participants