Flexible Styling

HellaJS supports both traditional CSS classes and CSS-in-JS styling approaches. Use regular CSS classes for existing stylesheets or CSS-in-JS for automatically scoped styles. Achieve dynamic styling through reactive class name bindings that respond to state changes.

Traditional CSS Classes

Apply CSS classes to elements using the class attribute, with full support for reactive class names and arrays using signal bindings.

Static Classes

Use regular CSS classes with external stylesheets.

const SimpleCounter = () => {
  const count = signal(0);
  
  return (
    <div class="counter-container">
      <h1 class="counter-display">{count}</h1>
      <button class="btn btn-primary" onClick={() => count(count() + 1)}>
        Increment
      </button>
    </div>
  );
};

Reactive Classes

Make CSS classes reactive using arrow functions.

const Counter = () => {
  const count = signal(0);
  
  return (
    <div class="counter-container">
      <h1 class={`counter-display ${count() % 2 === 0 ? 'even' : 'odd'}`}>
        {count}
      </h1>
      <button 
        class={`btn ${count() > 5 ? 'btn-success' : 'btn-primary'}`}
        onClick={() => count(count() + 1)}
      >
        {count() > 5 ? 'Great job!' : 'Increment'}
      </button>
    </div>
  );
};

Class Arrays

Use arrays for conditional classes.

const TodoItem = ({ todo }) => {
  return (
    <div class={[
      'todo-item',
      todo().done && 'completed',
      todo().priority === 'high' && 'priority-high',
      todo().editing && 'editing'
    ]}>
      {todo().text}
    </div>
  );
};

CSS-in-JS

HellaJS provides a css function for creating scoped styles with JavaScript objects. The CSS system now includes native reactive integration, allowing styles to automatically update when signals change, while maintaining backward compatibility with traditional static approaches.

Basic CSS Objects

Create styles using JavaScript objects with css properties.

const Counter = () => {
  const count = signal(0);
  
  const buttonStyle = css({
    padding: '0.75rem 1.5rem',
    border: 'none',
    borderRadius: '0.5rem',
    background: '#3b82f6',
    color: 'white',
    fontWeight: '600',
    cursor: 'pointer',
    transition: 'all 0.2s ease',
    
    '&:hover': {
      background: '#2563eb',
      transform: 'translateY(-1px)'
    }
  });
  
  return (
    <div>
      <h1>Count: {count}</h1>
      <button class={buttonStyle} onClick={() => count(count() + 1)}>
        Increment
      </button>
    </div>
  );
};

Reactive CSS Objects

CSS functions now work directly with reactive primitives for automatic style updates.

import { signal, effect } from '@hellajs/core';

const ThemeButton = () => {
  const theme = signal('light');
  const hovered = signal(false);
  
  // Reactive styles - automatically update when signals change
  effect(() => {
    const buttonStyle = css({
      padding: '0.75rem 1.5rem',
      border: 'none',
      borderRadius: '0.5rem',
      background: theme() === 'dark' ? '#374151' : '#3b82f6',
      color: theme() === 'dark' ? '#ffffff' : '#ffffff',
      opacity: hovered() ? 0.8 : 1,
      fontWeight: '600',
      cursor: 'pointer',
      transition: 'all 0.2s ease',
      
      '&:hover': {
        transform: 'translateY(-1px)'
      }
    });
    
    // The style automatically applies when signals change
  });
  
  return (
    <div>
      <h1>Count: {count}</h1>
      <button 
        onMouseEnter={() => hovered(true)}
        onMouseLeave={() => hovered(false)}
        onClick={() => theme(theme() === 'light' ? 'dark' : 'light')}
      >
        Toggle Theme ({theme()})
      </button>
    </div>
  );
};

Batched Reactive Updates

Multiple signal changes are automatically batched for optimal performance.

import { signal, effect, batch } from '@hellajs/core';

const MultiSignalStyles = () => {
  const backgroundColor = signal('#ffffff');
  const textColor = signal('#000000');
  const borderWidth = signal(1);
  
  effect(() => {
    const containerStyle = css({
      backgroundColor: backgroundColor(),
      color: textColor(),
      border: `${borderWidth()}px solid #ccc`,
      padding: '2rem',
      borderRadius: '0.5rem',
      transition: 'all 0.3s ease'
    });
  });
  
  const applyDarkTheme = () => {
    // All changes batched into single DOM update
    batch(() => {
      backgroundColor('#1a1a1a');
      textColor('#ffffff');
      borderWidth(2);
    });
  };
  
  return (
    <div>
      <button onClick={applyDarkTheme}>Apply Dark Theme</button>
      <p>Background: {backgroundColor()}</p>
      <p>Text: {textColor()}</p>
      <p>Border Width: {borderWidth()}px</p>
    </div>
  );
};

Dynamic Styling with Multiple Classes

Create different static CSS objects and choose between them reactively using class name bindings.

const Counter = () => {
  const count = signal(0);
  
  const evenStyle = css({
    padding: '2rem',
    borderRadius: '0.75rem',
    background: '#ecfdf5',
    border: '2px solid #d97706',
    transform: 'scale(1)',
    transition: 'all 0.3s ease'
  });
  
  const oddStyle = css({
    padding: '2rem',
    borderRadius: '0.75rem',
    background: '#fef3c7',
    border: '2px solid #059669',
    transform: 'scale(1.05)',
    transition: 'all 0.3s ease'
  });
  
  return (
    <div class={() => count() % 2 === 0 ? evenStyle : oddStyle}>
      <h1>Count: {count}</h1>
      <button onClick={() => count(count() + 1)}>Increment</button>
    </div>
  );
};

Style Composition

Create multiple CSS objects for different states and combine them with traditional CSS classes or conditional logic.

const TodoApp = () => {
  const todos = signal([
    { id: 1, text: 'Learn HellaJS', done: false },
    { id: 2, text: 'Build an app', done: true }
  ]);
  
  const baseItemStyle = css({
    padding: '1rem',
    margin: '0.5rem 0',
    borderRadius: '0.5rem',
    border: '1px solid #e5e7eb',
    background: 'white',
    transition: 'all 0.3s ease'
  });
  
  const completedItemStyle = css({
    padding: '1rem',
    margin: '0.5rem 0',
    borderRadius: '0.5rem',
    border: '1px solid #10b981',
    background: '#f0fdf4',
    opacity: 0.6,
    textDecoration: 'line-through',
    transition: 'all 0.3s ease'
  });
  
  const toggleTodo = (id) => {
    todos(todos().map(t => 
      t.id === id ? { ...t, done: !t.done } : t
    ));
  };
  
  return (
    <div>
      <h1>Todo List</h1>
      {forEach(todos, todo => (
        <div key={todo.id} class={todo.done ? completedItemStyle : baseItemStyle}>
          <input 
            type="checkbox" 
            checked={todo.done}
            onChange={() => toggleTodo(todo.id)}
          />
          <span>{todo.text}</span>
        </div>
      ))}
    </div>
  );
};

Style Scoping

HellaJS provides three scoping mechanisms to handle different styling scenarios.

Automatic Scoping (Default)

Every CSS object receives a unique class name based on its content hash, ensuring isolation without additional configuration.

Manual Scoping

You can add an additional scope prefix for extra organization, useful when building component libraries or complex applications.

Global Scoping

Styles are applied globally without any scoping, useful for base styles, resets, or library-wide utilities.

const ScopingExamples = () => {
  const isActive = signal(false);
  
  // Automatic scoping - generates unique class like 'c1a2b3c'
  const autoScopedButton = css({
    padding: '0.5rem 1rem',
    border: 'none',
    borderRadius: '0.25rem',
    background: '#f3f4f6',
    cursor: 'pointer'
  });
  
  // Manual scoping - applies styles within .my-component scope
  const manuallyScopedStyles = css({
    '.button': {
      padding: '0.5rem 1rem',
      border: 'none',
      borderRadius: '0.25rem'
    },
    '.button.active': {
      background: '#059669',
      color: 'white'
    }
  }, { scoped: 'my-component' });
  
  // Global scoping - applies styles globally (no class name returned)
  css({
    '*': {
      boxSizing: 'border-box'
    },
    'body': {
      margin: 0,
      fontFamily: 'system-ui, sans-serif'
    }
  }, { global: true });
  
  return (
    <div>
      {/* Automatic scoping example */}
      <button class={autoScopedButton}>
        Auto-scoped Button
      </button>
      
      {/* Manual scoping example */}
      <div class={manuallyScopedStyles}>
        <button 
          class={`button ${isActive() ? 'active' : ''}`}
          onClick={() => isActive(!isActive())}
        >
          Manually Scoped Button
        </button>
      </div>
      
      {/* Global styles are already applied document-wide */}
    </div>
  );
};

CSS Variables

HellaJS provides a dedicated cssVars function for managing CSS custom properties and theming with full reactive support.

Flattens nested objects into CSS custom property names (e.g., bg.primary becomes --bg-primary)
Injects properties into a :root rule in the document head
Returns an object mapping flattened keys to var() references
Manages cleanup when no longer referenced
New: Reactive updates when used with signals and effects

Traditional Approach

import { cssVars, css } from '@hellajs/css';

// Static CSS variables
const baseTheme = cssVars({
  colors: {
    primary: '#3b82f6',
    secondary: '#64748b',
    background: '#ffffff'
  },
  spacing: {
    small: '0.5rem',
    medium: '1rem',
    large: '2rem'
  }
});

const cardStyle = css({
  background: 'var(--colors-background)',
  color: 'var(--colors-primary)',
  padding: 'var(--spacing-large)',
  borderRadius: '0.5rem',
  border: '1px solid var(--colors-secondary)'
});

Reactive Approach

import { cssVars, css } from '@hellajs/css';
import { signal, effect } from '@hellajs/core';

const ReactiveThemeProvider = () => {
  const theme = signal('light');
  const accentColor = signal('#3b82f6');
  
  // Reactive CSS variables - automatically update when signals change
  effect(() => {
    const vars = cssVars({
      theme: {
        background: theme() === 'dark' ? '#0f172a' : '#ffffff',
        foreground: theme() === 'dark' ? '#f1f5f9' : '#1e293b',
        accent: accentColor(),
        muted: theme() === 'dark' ? '#374151' : '#f8fafc'
      },
      spacing: {
        xs: '0.25rem',
        sm: '0.5rem',
        md: '1rem',
        lg: '2rem'
      }
    });
  });
  
  const containerStyle = css({
    minHeight: '100vh',
    background: 'var(--theme-background)',
    color: 'var(--theme-foreground)',
    padding: 'var(--spacing-lg)',
    transition: 'all 0.3s ease'
  });
  
  const cardStyle = css({
    background: 'var(--theme-muted)',
    padding: 'var(--spacing-md)',
    borderRadius: '0.75rem',
    border: '2px solid var(--theme-accent)',
    margin: 'var(--spacing-md) 0'
  });
  
  return (
    <div class={containerStyle}>
      <div class={cardStyle}>
        <h1>Reactive Theme System</h1>
        <button onClick={() => theme(theme() === 'light' ? 'dark' : 'light')}>
          Toggle Theme ({theme()})
        </button>
        <input 
          type="color"
          value={accentColor()}
          onChange={e => accentColor(e.target.value)}
          style="margin-left: 1rem;"
        />
        <p>Theme updates automatically when signals change!</p>
      </div>
    </div>
  );
};

Batched Theme Updates

import { batch } from '@hellajs/core';

const ThemeController = () => {
  const theme = signal('light');
  const primaryColor = signal('#3b82f6');
  const secondaryColor = signal('#64748b');
  
  effect(() => {
    cssVars({
      colors: {
        primary: primaryColor(),
        secondary: secondaryColor(),
        background: theme() === 'dark' ? '#000' : '#fff'
      }
    });
  });
  
  const applyBlueTheme = () => {
    batch(() => {
      theme('light');
      primaryColor('#3b82f6');
      secondaryColor('#1e40af');
    }); // Single efficient update
  };
  
  const applyRedTheme = () => {
    batch(() => {
      theme('dark');
      primaryColor('#ef4444');
      secondaryColor('#dc2626');
    }); // Single efficient update
  };
  
  return (
    <div>
      <button onClick={applyBlueTheme}>Blue Theme</button>
      <button onClick={applyRedTheme}>Red Theme</button>
    </div>
  );
};

Internal Mechanics

High performing CSS-in-JS through intelligent design.

Reactive Style Integration

The styling system seamlessly integrates with HellaJS’s reactive core, creating a unified approach where style updates benefit from the same dependency tracking and batching optimizations as other reactive computations.

Signal Change → Effect Update → Style Recalculation → Batched DOM Update
     ↑                                                          ↓
     └─── Dependency Tracking & Auto Cleanup ──────────────────┘

Enhanced Reactive Features:

Automatic Updates - CSS automatically recalculates when dependent signals change
Intelligent Batching - Multiple signal changes result in single DOM updates (60-80% performance improvement)
Granular Dependencies - Only styles using changed signals recalculate
Memory Efficiency - Reactive style bindings cleanup automatically with effects
Zero Overhead - Static styles have no reactive overhead
Seamless Integration - Works naturally with existing reactive patterns

Smart Caching System

HellaJS implements an intelligent multi-layer caching system that recognizes when identical CSS objects are used across different components.

CSS Object → Content Hash → Cache Lookup → Class Name
    ↓              ↓              ↓             ↓
{color:'red'} → 'abc123' → Hit/Miss → '.cabc123'

Caching layers.

Content-Based Hashing - Identical CSS objects always produce the same hash
Class Name Cache - Maps CSS hashes to generated class names
Reference Counting - Tracks usage for automatic cleanup
Inline Memoization - Fast lookup for recently used styles

Performance benefits.

Reduced Bundle Size - Duplicate styles create only one CSS rule
Memory Efficiency - Shared class names across components
O(1) Lookups - Previously processed styles return instantly

Automatic Memory Management

Unlike traditional CSS-in-JS solutions that can accumulate styles over time, HellaJS provides comprehensive memory management through reference counting.

Component Mount    → Style Used     → Reference Count++
Component Unmount  → Style Unused   → Reference Count--
Reference Count 0  → Style Cleanup  → CSS Rule Removed

Memory management features.

Reference Tracking - Each style tracks how many components use it
Automatic Cleanup - Unused styles are removed from DOM automatically
Leak Prevention - No CSS accumulation in long-running applications
Manual Control - css.remove() for precise lifecycle management

Scoping and Isolation

Every CSS-in-JS style receives automatic scoping through content-based hashing, ensuring complete style isolation without configuration.

Input:  css({ padding: '1rem', color: 'blue' })
Hash:   'a1b2c3'
Output: '.ca1b2c3 { padding: 1rem; color: blue; }'

Scoping mechanisms.

Automatic Scoping - Content-based hashing creates unique class names
Manual Scoping - Optional prefixes for component libraries
Global Scoping - Bypass scoping for application-wide styles
Predictable Names - Identical styles always generate same class names