Array Variable

An array variable lets you define a series of values. Items can be scalar values, objects, or a mix of both. Long lists can be created in shorthand with range syntax.

Definition

Defined with the --name: [item, item, ...]; syntax.

--variants: [light, dark, violet];
--steps: [1-12];
--spaces: [4px-24px];
--letters: [A-F];
--breakpoints: [{ name: sm; size: 640px }, { name: md; size: 768px }];

Access Forms

Syntax	What it returns
`var(--variants)`	All items
`var(--variants[0])`	Access by index. First item starts at 0
`var(--breakpoints[0].name)`	Index and key access on an object item

Range Syntax

The [start-end] shorthand can be used for consecutive values.

Number Range

--steps: [1-4];

This is shorthand for:

--steps: [1, 2, 3, 4];

Unit Range

--spaces: [4px-8px];

This is shorthand for:

--spaces: [4px, 5px, 6px, 7px, 8px];

Letter Range

--letters: [A-F];

This is shorthand for:

--letters: [A, B, C, D, E, F];

Reverse Order

Ranges can also be written in reverse order:

--countdown: [4-1];    /* [4, 3, 2, 1] */
--lettersRev: [F-C];   /* [F, E, D, C] */

Quoted Range Difference

Values inside quotes are not expanded as a range; they are accepted as a single string item.

Writing	Result
`[A-F]`	`[A, B, C, D, E, F]` — letter range
`['A-F']`	`['A-F']` — single string item
`["A-F"]`	`["A-F"]` — single string item

--range: [A-F];       /* 6 items: A, B, C, D, E, F */
--literal: ['A-F'];   /* 1 item: 'A-F' */

Unit-Range Behavior

If start and end units differ in a range, compilation does not stop; an invalid-array-range-unit warning is produced and intermediate values are filled with default logic.

--mixed: [1px-3rem];

Generated intermediate form:

--mixed: [1px, 2px, 3rem];

First item keeps its own unit
Last item keeps its own unit
Intermediate items are filled with the start unit

Scalar Array

Items can be strings, numbers, or CSS values.

--sizes: [sm, md, lg];

@for((size,index), var(--sizes)) {
  .btn-${size} { font-size: ${(index + 1) * 4}px; }
}

Generated CSS:

.btn-sm { font-size: 4px; }
.btn-md { font-size: 8px; }
.btn-lg { font-size: 12px; }

Array of Objects

When items are objects, key access can be done with var(--arr[index].key) syntax.

--breakpoints: [
  { name: sm; size: 640px },
  { name: md; size: 768px },
  { name: lg; size: 1024px }
];

@for(bp, var(--breakpoints)) {
  @media (min-width: ${bp.size}) {
    .container-${bp.name} {
      max-width: ${bp.size};
    }
  }
}

Generated CSS:

@media (min-width: 640px) {
  .container-sm { max-width: 640px; }
}

@media (min-width: 768px) {
  .container-md { max-width: 768px; }
}

@media (min-width: 1024px) {
  .container-lg { max-width: 1024px; }
}

Mixed Array

Object and scalar items can coexist in the same array.

--tones: [{ 100: #f8faff; 900: #0a1628; }, midgray, { 100: #f5f5f5; }];

For object items, key access like var(--tones[0].100) can be used.
For scalar items, direct index access like var(--tones[1]) can be used.

.color-a {
  background: var(--tones[0].100);  /* #f8faff */
}

.color-b {
  color: var(--tones[1]);           /* midgray */
}

Generated CSS:

.color-a {
  background: #f8faff;
}

.color-b {
  color: midgray;
}

Index Access in Selector

An array item can be used as a selector part. Key access on arrays of objects and direct index access on scalar arrays are both supported.

Array of Objects — Key Access

--breakpoints: [{ name: sm; size: 640px }, { name: md; size: 768px }];

.bp-&var(--breakpoints[0].name) {
  max-width: var(--breakpoints[0].size);
}

Generated CSS:

.bp-sm {
  max-width: 640px;
}

Scalar Array — Direct Index Access

In scalar arrays, the item value can be used directly inside a selector. In a property value, the same item can be appended without a space to preceding text with &var(...).

--color-range: [A-F];

.bp-var(--color-range[0]) {
  color: #AA&var(--color-range[0]);
}

var(--color-range[0]) gives the first item, i.e. A. var(--color-range[0]) in the selector → .bp-A, #AA&var(--color-range[0]) in the declaration → #AAA.

Generated CSS:

.bp-A {
  color: #AAA;
}

You can combine with @for for all items:

--color-range: [A-F];

@for(c, var(--color-range)) {
  .bp-${c} {
    color: ${"#AA" + c};
  }
}

Generated CSS:

.bp-A { color: #AAA; }
.bp-B { color: #AAB; }
.bp-C { color: #AAC; }
.bp-D { color: #AAD; }
.bp-E { color: #AAE; }
.bp-F { color: #AAF; }