FSCSS Arrays v1.1.14+ - Complete Guide with New Array Methods

Introduction to FSCSS Arrays

FSCSS Arrays let you store organized collections of values that can be reused throughout your stylesheets. Perfect for color palettes, spacing systems, animation timing, and any situation where you need consistent, reusable values.

Organized Collections

Store related values together in logical groups

Dynamic Access

Access values by index for flexible styling

Combination Power

Combine with @random, @fun, and other FSCSS features

Clean Syntax

Intuitive array declaration and access patterns

FSCSS Array Methods New in v1.1.14+

Method Access Mode

FSCSS arrays are string-native data structures designed to generate CSS efficiently. Unlike traditional script arrays, they return strings directly, making them ideal for reducing repetition and generating utility patterns at compile time.

Key Characteristics

String-native – All transformations output final string values
No method chaining – Arrays return directly, not objects
No nested execution – Array declarations don't resolve inner arrays

Access Modes

Direct Output (Space Separated)

@arr.name
// Returns: item1 item2 item3

Method Access Mode

@arr.name!
// Enables: @arr.name!.reverse, @arr.name!.length, etc.

Available Array Methods

Complete Method Reference

Method	Description	Example	Output
`.length`	Returns number of items	`@arr.n!.length`	3
`.first`	Returns first item	`@arr.n!.first`	item1
`.last`	Returns last item	`@arr.n!.last`	item3
`.list`	Comma-separated list	`@arr.n!.list`	item1,item2,item3
`.join(sep)`	Join with custom separator	`@arr.n!.join(+)`	item1+item2+item3
`.reverse`	Reverse order (comma list)	`@arr.n!.reverse`	item3,item2,item1
`.shuffle`	Random order (comma list)	`@arr.n!.shuffle`	item2,item3,item1
`.sort`	Alpha/numeric sort	`@arr.n!.sort`	item1,item2,item3
`.unique`	Remove duplicates	`@arr.n!.unique`	item1,item2,item3
`.indices`	1-based indices	`@arr.n!.indices`	1,2,3
`.randint`	Returns a random item	`@arr.n!.randint`	item2
`.segment`	Wrap in [] brackets	`@arr.n!.segment`	[item1][item2][item3]
`.sum`	Sum numeric values	`@arr.num!.sum`	15
`.min`	Minimum numeric value	`@arr.num!.min`	4
`.max`	Maximum numeric value	`@arr.num!.max`	16
`.unit(val)`	Append unit to each	`@arr.n!.unit(px)`	4px,8px,12px
`.prefix(v)`	Add prefix to each	`@arr.b!.prefix(btn-)`	btn-A,btn-B,btn-C
`.surround(b,a)`	Wrap each item	`@arr.b!.surround([,])`	[A][B][C]

Array Mutation

Adding and Removing Items

Add Items

@arr.name!+[item4, item5]

Remove Item (1-based index)

@arr.name!-[2] // Removes second item

Important Limitations

No Method Chaining

The following will not work:

@arr.name!.unit(px)!.join(+) // Invalid

Each method returns a string, not an array object.

No Nested Array Execution

The following will not resolve the inner array:

@arr.b[@arr.a!.list] // Stores literal string, doesn't execute

Design Philosophy

FSCSS arrays are intentionally constrained to excel at their primary purpose:

String-output generators – Direct transformation to CSS values
Repetition reducers – Eliminate manual duplication
Utility pattern generators – Create systematic CSS variations

This focused approach ensures predictable, performant CSS generation without the complexity of full scripting capabilities.

Practical Examples with New Methods

Gradient Generator

FSCSS

@arr colors[#1E2783, #8C29B2, #C41348]

.box {
  background: linear-gradient(40deg, @arr.colors!.list);
}
/* Output: background: linear-gradient(40deg, #1E2783,#8C29B2,#C41348); */
 
.box-2 {
  background: linear-gradient(40deg, @arr.colors!.reverse);
}
/* Output: background: linear-gradient(40deg,#C41348,#8C29B2,#1E2783); */

Spacing Utilities with .unit()

FSCSS

@arr spaces[8, 12, 16, 24]

.m-@arr.spaces[] {
  margin: @arr.spaces[]px;
}

/* Or using .surround() method */
.card {
  padding: @arr.spaces!.surround(,rem);
}
/* Output: padding: 8rem 12rem 16rem 24rem; */

Component Variants with .randint()

FSCSS

@arr colors[#0066FF, #6B7280, #10B981, #F59E0B, #EF4444]

.btn-a {
  background: @arr.colors!.randint;
}
.btn-b {
  background: @arr.colors!.randint;
}

Reducing Typing with %n() Loop

FSCSS

@arr sizing[width, height, max-width, max-height, min-height, min-width];
  
/* store array reference */
$sizing: @arr.sizing!;
  
.box {
  %6($sizing.list[: 200px;])
}
/* Output: 
width: 200px; 
height: 200px; 
max-width: 200px; 
max-height: 200px; 
min-height: 200px; 
min-width: 200px;
*/

Basic Array Declaration

Creating and Using Arrays

@arr

The simplest form of FSCSS arrays. Define collections of values and access them by index throughout your stylesheet.

FSCSS

/* Define arrays */
@arr(colors[#3b82f6, #8b5cf6, #06b6d4, #10b981]);
@arr(spacing[0.5rem, 1rem, 1.5rem, 2rem, 3rem]);
@arr(font-sizes[12px, 14px, 16px, 18px, 24px, 32px]);

/* Use array values */
.primary-button {
  background: @arr.colors[1];
  color: white;
  padding: @arr.spacing[2] @arr.spacing[3];
  font-size: @arr.font-sizes[3];
  border-radius: 4px;
}

.secondary-button {
  background: @arr.colors[2];
  color: white;
  padding: @arr.spacing[1] @arr.spacing[2];
  font-size: @arr.font-sizes[2];
}

.primary-button {
  background: #3b82f6;
  color: white;
  padding: 1.5rem 2rem;
  font-size: 18px;
  border-radius: 4px;
}

.secondary-button {
  background: #8b5cf6;
  color: white;
  padding: 1rem 1.5rem;
  font-size: 16px;
}

Dynamic Array Usage

Auto-Indexing and Looping

Dynamic Arrays

Arrays can automatically iterate through their values when used with empty brackets, making them perfect for generating multiple similar styles with variations.

FSCSS

/* Define arrays for staggered animations */
@arr(delays[0.1s, 0.3s, 0.5s, 0.7s, 0.9s]);
@arr(colors[#ef4444, #f59e0b, #10b981, #3b82f6, #8b5cf6]);
/* helper for indexes */
@arr(indexes[count(5, 1)])
/* Auto-index through array values */

.loading-dot:nth-child(@arr.indexes[]) {
/* capture current index using FSCSS scope variable*/
  $index: @arr.indexes[];
  animation: bounce 1.5s infinite @arr.delays[$index!];
  background: @arr.colors[$index!];
}

@keyframes bounce {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-15px); }
}

.loading-dot:nth-child(1) {
  animation: bounce 1.5s infinite 0.1s;
  background: #ef4444;
}

.loading-dot:nth-child(2) {
  animation: bounce 1.5s infinite 0.3s;
  background: #f59e0b;
}

.loading-dot:nth-child(3) {
  animation: bounce 1.5s infinite 0.5s;
  background: #10b981;
}

.loading-dot:nth-child(4) {
  animation: bounce 1.5s infinite 0.7s;
  background: #3b82f6;
}

.loading-dot:nth-child(5) {
  animation: bounce 1.5s infinite 0.9s;
  background: #8b5cf6;
}

@keyframes bounce {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-15px); }
}

Arrays with @random

Random Value Selection

@random + Arrays

Combine arrays with the @random function to create dynamic, ever-changing styles that select random values from your predefined collections.

FSCSS

/* Define arrays of possible values */
@arr(backgrounds[#3b82f6, #8b5cf6, #06b6d4, #10b981, #f59e0b, #ef4444]);
@arr(rotations[0deg, 5deg, -5deg, 10deg, -10deg]);
@arr(scales[1, 1.05, 1.1, 0.95, 0.9]);

/* Apply random values from arrays */
.dynamic-card {
/* array join method */
  background: @random([@arr.backgrounds(,)]);
  transform: 
    rotate(@random([@arr.rotations(,)])) 
    scale(@random([@arr.scales(, )]));
  padding: 2rem;
  border-radius: 8px;
  transition: all 0.3s ease;
}

.dynamic-card:hover {
  transform: 
    rotate(@random([@arr.rotations(,)])) 
    scale(@random([@arr.scales(, )]));
}

/* Note: @random generates different values on each compilation */
.dynamic-card {
  background: #8b5cf6; /* Random selection */
  transform: rotate(5deg) scale(1.05); /* Random selection */
  padding: 2rem;
  border-radius: 8px;
  transition: all 0.3s ease;
}

.dynamic-card:hover {
  transform: rotate(-5deg) scale(1.1); /* Random selection */
}

Dynamic Card

Arrays with @fun

Function-Based Arrays

@fun + Arrays

Combine arrays with the @fun function to create reusable collections of related values that can be accessed through a clean, organized interface.

FSCSS

/* Define function-based arrays */
@fun(theme){
  primary: #3b82f6;
  secondary: #8b5cf6;
  accent: #06b6d4;
  success: #10b981;
  warning: #f59e0b;
  danger: #ef4444;
}

@fun(spacing){
  xs: 0.5rem;
  sm: 1rem;
  md: 1.5rem;
  lg: 2rem;
  xl: 3rem;
}

/* Use function-based arrays */
.alert {
  padding: @fun.spacing.md.value @fun.spacing.lg.value;
  border-radius: 4px;
  margin-bottom: @fun.spacing.sm.value;
}

.alert-success {
  background: @fun.theme.success.value;
  color: white;
}

.alert-warning {
  background: @fun.theme.warning.value;
  color: white;
}

.alert-danger {
  background: @fun.theme.danger.value;
  color: white;
}

.alert {
  padding: 1.5rem 2rem;
  border-radius: 4px;
  margin-bottom: 1rem;
}

.alert-success {
  background: #10b981;
  color: white;
}

.alert-warning {
  background: #f59e0b;
  color: white;
}

.alert-danger {
  background: #ef4444;
  color: white;
}

Success Alert

Warning Alert

Danger Alert

Array Types Comparison

Choosing the Right Array Type

Different array types serve different purposes. Choose the right one for your use case.

Array Type	Syntax	Best For	Example Use Case
Basic Arrays	`@arr(name[val1, val2])`	Simple value collections	Color palettes, spacing scales
Method Arrays v1.1.14+	`@arr.name!.method`	Transforming array values	.reverse, .shuffle, .unit(px), .prefix(btn-)
Dynamic Arrays	`@arr.name[]` (auto-index)	Generating multiple similar styles	Staggered animations, grid systems
@random Arrays	`@random([@arr.name(,)])`	Dynamic, varied styling	Random backgrounds, interactive elements
Arrays join	`@arr.name(separator)`	Separate array with words or character	commonly used with random and similar functions
@fun Arrays	`@fun(name){key: value}`	Organized design systems	Theming, design tokens, component libraries

Real World Examples

Practical Applications

Here are some practical examples of how arrays can be used in real projects:

Design System

@arr(colors[#1e40af, #1d4ed8, #3b82f6, #60a5fa]);
@arr(spacing[0.25rem, 0.5rem, 1rem, 1.5rem, 2rem]);

.btn {
  padding: @arr.spacing[2] @arr.spacing[3];
  border-radius: 4px;
  font-weight: 600;
}

.btn-primary {
  background: @arr.colors[2];
  color: white;
}

Animation System

@arr(delays[0s, 0.1s, 0.2s, 0.3s, 0.4s]);
@arr(durations[0.3s, 0.5s, 0.7s, 1s]);

.fade-in:nth-child(@arr.delays[]) {
  animation: fadeIn @arr.durations[2] @arr.delays[];
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

Grid System

@arr(columns[1, 2, 3, 4, 6, 12]);
@arr(gaps[0.5rem, 1rem, 1.5rem, 2rem]);

.grid-@arr.columns[] {
  display: grid;
  grid-template-columns: repeat(@arr.columns[], 1fr);
  gap: @arr.gaps[2];
}

Best Practices

Using Arrays Effectively

Follow these guidelines to make the most of FSCSS arrays in your projects.

Naming Conventions

Use plural names: colors, spacings, sizes
Be descriptive: primary-colors vs colors1
Group related arrays with prefixes

Organization

Define arrays at the top of your file
Group related arrays together
Use comments to document array purposes
Consider using @fun for complex design systems

Advanced Tips

Combine with @random for dynamic interfaces
Use auto-indexing for repetitive patterns
Create array-based design systems
Document your arrays for team collaboration
Use method access mode (!) only when needed
Plan array structure before applying methods

Summary: Why FSCSS Arrays?

Feature	Benefit
String-native	Predictable CSS output
Simple syntax	Minimal learning curve
Focused methods	Purpose-built for CSS
Direct output	Easy debugging

Use them to:

Generate color palettes and gradients
Create systematic spacing scales
Build component variant systems
Manage responsive breakpoints
Reduce manual repetition

Avoid them for:

Complex data manipulation
Nested data structures

FSCSS arrays: Simple by design, powerful in practice