Skip to content

fix: keep a list's separator when read through variables or custom properties - #575

Merged
danstepanov merged 10 commits into
nativewind:mainfrom
sammoore:fix/list-separator
Nov 18, 2026
Merged

danstepanov merged 10 commits into
nativewind:mainfrom
sammoore:fix/list-separator

Conversation

@sammoore

@sammoore sammoore commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Supersedes #547 with the following modifications:

  • for perf:
    • resolve a list in one pass instead of using two resolvers (see commit for more info)
    • use shadows as-is if they have already been resolved
    • reduce cost of lists on Hermes:
      • a list led by a function runs Object.keys once instead of twice
      • one-token comma items skip building and resetting an item array
      • items array is allocated only when there's a comma
      • `applyValue`` checks for comma lists only on objects (plain values skip it)
    • unwrap transform arguments without a second style function test
  • simplified diff / what PR addresses:

Problem

When resolving a var() or custom property at runtime, a comma-separated list inside the value compiles to the same array as a space-separated one. At runtime, this means e.g. we must guess whether the separators are a space or a comma.

This is usually fine: often the guess is obvious (we have few edge-cases), or we don't even have to guess because single-use variables are replaced at build-time (unless inlineVariables: false).

However, it can cause discrepancies relative to how a browser renders shadows, gradients, rgb(... / a), and transforms. In some cases it completely breaks the resulting rule, such that it doesn't apply.

main this branch
box-shadow: var(--o) var(--b) over --o: 1px 2px; --b: 3px 4px #123 3px 4px #123 1px 2px 3px 4px #123
box-shadow: var(--a) over --b: 1px 2px; --a: var(--b) 3px 4px #123 no shadow 1px 2px 3px 4px #123
box-shadow: var(--s) #456 over --s: 1px 1px 0 0 #123, 2px 2px 0 0 a second shadow with no colour 2px 2px 0 0 #456
transform: var(--t) over --t: rotate(45deg) translateX(10px) [[{ rotate }, { translateX }]], which React Native refuses [{ rotate }, { translateX }]
linear-gradient(to right, var(--c)) over --c: #123, #456 linear-gradient(to right, #123 #456) linear-gradient(to right, #123, #456)
background-color: rgb(var(--c) / 0.5) over --c: 255 0 0 rgb(255 0 0, 0.5) rgb(255 0 0 / 0.5)

Solution

  • reduceParseUnparsed keeps each item of a list of two or more as the array of its tokens, as before fix: parsing of rules with comma seperated styles #24; a lone item stays bare. parseGradient, parseUnresolvedColor and an @property comma multiplier build their lists the same way, and the stylesheet builder still marks a list for runtime resolution when a function such as var() sits inside one of its items.
  • resolveValue then substitutes a var() by its tokens, as css-variables-1 §3 does: a list joins the item the var() stands in, and a comma-separated one splits that item.
  • boxShadow reads a comma-separated list's items as shadows, resolving each shadow once. The function printer joins items with , and tokens with a space. filter reads a comma-separated list as its filters, as main does. translate(), scale() and rotate() read each written argument in its place, and the timing functions and platformColor read their arguments' items.
  • applyValue and useNativeVariable hand out a comma-separated list with one-token items bare, the form React Native's list props take, so transitionProperty: var(--p) gets what it gets today.

Tests

src/__tests__/native/variable-lists.test.tsx (50 cases). The first four groups below each run twice: once with the variable folded in at build time, and once kept for runtime (inlineVariables: false).

  • Tests for space- and comma-separated lists read through a variable: box-shadow, filter, transform, text-shadow, transition-property, and a var() inside translate() / scale() arguments.
    • box-shadow: var(--o) var(--b) should draw one shadow, not two.
    • box-shadow: var(--s) #456 over a comma list should give the colour to the last shadow.
    • transform: var(--t) should reach React Native as a flat list.
  • Tests for functions printed back as text: gradient stops keep their commas, rgb(var(--c) / 0.5) keeps its /, and linear-gradient(var(--c)) over #123 #456 keeps its space.
  • Tests for timing functions held in a variable: steps() and cubic-bezier().
  • A test for a variable holding translateZ(10px) rotate(45deg): expects the list without translateZ(), which react-native-css has no form for.
  • A test for an invalid list: two shadows written without a comma replace an earlier rule's shadow with none.
  • Tests for var() fallbacks holding a space- or comma-separated list.
  • Tests for what React Native's list props receive: transition-property: var(--p) and useNativeVariable("--p") still get a flat list such as ["width", "opacity"].
  • Tests for resolving an already-resolved list again, as happens when an element reads the same variable twice. The list should keep its shape.
  • Tests for list shapes that are resolved directly, such as a token list nested in a space-separated list, or rotate() with three comma-separated arguments.

src/__tests__/compiler/compiler.test.tsx (8 cases)

  • Tests that a custom property keeps its separator: blue, green, blue ,green and blue/**/, green compile differently from blue green, and the same holds for multi-token items such as 1px 2px #000, 3px 4px #fff.
  • Tests that box-shadow: var(--a), var(--b) compiles differently from var(--a) var(--b).

src/__tests__/compiler/property.test.ts (1 case)

  • A test that an @property with a comma-separated repeated value (<length>#) keeps each item of its initial value apart.

YevheniiKotyrlo and others added 10 commits November 17, 2026 16:35
A comma-separated list compiled to the same array as a space-separated
one whenever each item was a single token, so the runtime guessed the
separator from how its arrays nested: box-shadow: var(--o) var(--b) drew
the second variable as a shadow of its own, a transform held in a
variable reached React Native as a nested list, and a comma in a filter
or transform list went unnoticed.

The compiler keeps each item of a comma-separated list as the array of
its tokens, and the runtime substitutes a var() by its tokens as
css-variables-1 §3 does, so box-shadow, filter, transform, the
arguments of translate(), scale() and rotate() and the function printer
read the separator a list was written with. A transform list holds one
function per token: translate()'s second offset, which React Native
refused nested, joins the list, and a function the compiler writes no
form for drops out without taking the list with it. React Native's list
props still take a comma-separated list with one-token items bare.
…cheaply

Follow-up to the separator fix. resolveCommaList and resolveTokens, which
handed lists back and forth and re-detected a comma-separated list led by
an object, become one resolveList: each entry's tokens are resolved and
appended to the current item, and a resolved list is substituted by
appendList (a space-separated one joins the item, a comma-separated one
splits it).

A resolved value holds no style functions, so isCommaList and
commaListItems now test only resolved values, with Array.isArray alone
instead of isStyleFunction's Object.keys call; the one reader of a
descriptor, transformArguments, tests its arguments with
isStyleDescriptorArray. Behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
boxShadow resolves its argument list once, then handed each shadow to the
shorthand handler with resolveValue, which resolved every token again.
Pass an identity resolver so the handler only matches the shadow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The separator fix rewrote reduceParseUnparsed and moved its <ratio> case
into a helper. Two changes to the original are enough: each comma group
stays an array, so a one-token item stays distinct from a token of a
space-separated list, and a lone group is unwrapped at the end as before.
The compiled output is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…g a var()

The separator fix compiles a comma-separated argument list as items, so
translate(), scale() and rotate() must unwrap each one-token argument. It
also added a reader that spreads a lone var() holding a comma-separated
list into the arguments (translate(var(--t)) over --t: 10px, 20px) and
reads translate() with one var() argument. Neither concerns the separator,
so this keeps the original resolvers and only unwraps each argument;
translate(var(--t)), scale(var(--s)) over a comma list and a lone
translate(var(--x)) render as they do on main, and their cases go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The separator fix made filter and transform return null for a
comma-separated list, as browsers drop the declaration. That enforces a
grammar rather than keeping a separator, so this keeps main's lenient
reading:

- filter flattens a comma-separated list into its filters, as main's
  flat(Infinity) did. Only a comma-separated list nests now that
  resolveValue splices a var() in, so it flattens one level and only for
  such a list.
- transform renders a comma-separated list's functions in order.

Neither hands React Native anything it refuses. Tailwind never writes a
comma in either property, and its filter, transform and shadow utilities
render identically on main, the separator fix and here. The filter and
transform cases of the "replaces an earlier rule's value" table go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Flattening translate()'s second offset and writing nothing for an
unsupported function such as translateZ() is a transform fix that nativewind#389
makes too, in its rewrite of parseTransform. It isn't needed to keep a
list's separator, so this branch leaves it to nativewind#389.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keeping a list's separator made a comma-separated list read through a
var() (transition-property, font-family) and a list led by a var() cost
more on Hermes than main's map + filter. This trims that work without
changing any output:

- resolveList classifies its first entry once, and tells resolveValue
  when it is already known to be a style function, so isStyleFunction's
  Object.keys (the cheapest empty-object test on Hermes) runs once for
  that token instead of twice.
- A one-token item of a comma-separated list is pushed as [token]
  without building and resetting an item, and the list of items is
  allocated only once a comma appears.
- applyValue tests for a comma-separated list only inside its existing
  object branch, so a string or number declaration pays nothing for it;
  the guard had cost 1-2.5% on single-token declarations.
- Indexed loops, and push instead of map() or new Array(n), which Hermes
  runs slower.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
Since nativewind#567 a registered custom property's initial value is compiled into
vp (name, inherits, initial value) instead of vr, so this test, written
against the old shape, found nothing and failed once the branch was
tested against main. The compiler keeps the separator either way: the
value is [[10], [20]], one item per comma.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
…tion test

argument() unwraps each one-token argument of translate(), scale() and
rotate() with isStyleDescriptorArray, whose isStyleFunction runs
Object.keys, and resolveValue then runs the same test on the token. An
argument is always a compiled descriptor, where only a style function
starts with its {} marker, so an array of one entry that isn't a plain
object is an item, and typeof and Array.isArray tell them apart.

On Hermes (list-bench, against bench), Tailwind's translate-x-4
rotate-45 scale-110 with its variables resolved at runtime goes from
+6.1% to +1.6%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D4jU1dW7KKQntNrr9i2xGi
@danstepanov
danstepanov merged commit 7d41636 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.

3 participants