Styler

@vitus-labs/styler is a CSS-in-JS engine replacing styled-components. It provides a familiar tagged template literal API with static/dynamic path optimization, automatic class name hashing, and React 19 SSR support.

Installation

npm install @vitus-labs/styler

Peer dependencies: react >= 19, react-dom >= 19

Key Features

• ~10.3 KB gzipped — full-featured engine with SSR, @layer, and concurrent-mode-safe injection
• Static/dynamic split — Templates without function interpolations compute class once at definition time (zero per-render cost)
• FNV-1a hashing — Deterministic class names, automatic deduplication
• CSS-in-CSS composition — Nest css results inside styled or other css calls
• React 19 SSR — <style precedence> on server, useInsertionEffect on client
• Transient props — $-prefixed props consumed by styles but never forwarded to DOM
• Polymorphic as prop — Render as any element or component
• Specificity boost — Double selector option for library component overrides
• @layer support — CSS cascade layer wrapping
• Bounded cache — Configurable max cache size with automatic eviction

Try It Live

function StyledDemo() {
const [color, setColor] = React.useState('#0d6efd')
const [radius, setRadius] = React.useState(8)

return (
  <div style={{ fontFamily: 'system-ui' }}>
    <div style={{ display: 'flex', gap: 12, marginBottom: 12 }}>
      <label style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 14 }}>
        Color:
        <input type="color" value={color} onChange={(e) => setColor(e.target.value)} />
      </label>
      <label style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 14 }}>
        Radius: {radius}px
        <input type="range" min={0} max={24} value={radius} onChange={(e) => setRadius(Number(e.target.value))} />
      </label>
    </div>
    <button style={{
      background: color,
      color: 'white',
      border: 'none',
      borderRadius: radius,
      padding: '10px 20px',
      fontSize: 14,
      cursor: 'pointer',
      fontWeight: 500,
    }}>
      Styled Button
    </button>
  </div>
)
}

render(<StyledDemo />)

css()

Tagged template for composable CSS fragments. Returns a lazy CSSResult object — no CSS resolution happens at creation time.

import { css } from '@vitus-labs/styler'

// Static — stored as-is, resolved when consumed
const highlight = css`
  color: red;
  font-weight: bold;
`

// Dynamic — function interpolations resolved at render time with props + theme
const dynamic = css`
  color: ${(props) => props.$color || 'blue'};
  padding: ${(props) => props.$size}px;
`

// Composition — nest css results inside other css
const combined = css`
  ${highlight}
  border: 1px solid gray;
`

// Array interpolation — flattened automatically
const responsive = css`
  ${[
    css`color: red;`,
    css`margin: 0;`,
  ]}
`
// Resolves to: "color: red;margin: 0;"

CSSResult

css() returns a CSSResult instance that stores the raw template strings and interpolation values:

class CSSResult {
  readonly strings: TemplateStringsArray
  readonly values: Interpolation[]

  // Resolve with empty props (useful for testing/debugging)
  toString(): string
}

• No computation at creation time — only stores references
• Resolved when consumed by styled, useCSS, or toString()
• Instance check: value instanceof CSSResult detects nested CSS for composition
• Thunk pattern: When used as interpolation before engine init, returns a thunk resolved at render

Interpolation Types

type Interpolation =
  | string
  | number
  | boolean
  | null
  | undefined
  | CSSResult
  | Interpolation[]   // recursive
  | ((props: { theme?: DefaultTheme; [key: string]: any }) => Interpolation)

CSS Normalization

Resolved CSS goes through a single-pass normalization that:

• Strips /* block comments */ and // line comments (preserves :// in URLs)
• Collapses whitespace to single spaces
• Removes redundant semicolons (after {, }, other ;)

styled()

Component factory that creates styled React components with automatic class name management, ref forwarding, and prop filtering.

import { styled } from '@vitus-labs/styler'

// Tag shorthand via Proxy
const Box = styled.div`
  padding: 16px;
  border-radius: 8px;
`

// Direct call syntax
const Card = styled('section')`
  background: white;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
`

// Wrap existing component
const StyledButton = styled(MyButton)`
  cursor: pointer;
`

// With options
const Custom = styled('div', {
  shouldForwardProp: (prop) => !prop.startsWith('custom'),
  boost: true,
})`
  padding: 16px;
`

Options

styled(tag: string | ComponentType, options?: StyledOptions)

Dynamic Props & Transient Props

Props prefixed with $ are automatically filtered from DOM output:

const Button = styled.button`
  background: ${(props) => props.$variant === 'primary' ? '#0d6efd' : '#6c757d'};
  color: white;
  padding: ${(props) => props.$size === 'large' ? '12px 24px' : '8px 16px'};
`

<Button $variant="primary" $size="large">Click me</Button>
// Renders: <button class="vl-abc123">Click me</button>
// $variant and $size consumed by styles, NOT forwarded to <button>

Polymorphic as Prop

Override the rendered element type at the call site:

const Box = styled.div`
  padding: 16px;
`

<Box as="section" />      // renders <section>
<Box as="article" />      // renders <article>
<Box as={MyComponent} />  // renders <MyComponent>

The as prop works in both static and dynamic paths and is never forwarded to the underlying element.

Ref Forwarding

All styled components forward refs via React.forwardRef:

const Input = styled.input`
  border: 1px solid gray;
`

const ref = useRef<HTMLInputElement>(null)
<Input ref={ref} />  // ref points to the <input> DOM element

shouldForwardProp

For custom prop filtering logic:

const Input = styled('input', {
  shouldForwardProp: (prop) => prop !== 'hasError',
})`
  border-color: ${(props) => props.hasError ? 'red' : 'gray'};
`

<Input hasError />
// hasError used by styles but NOT forwarded to <input>

shouldForwardProp only applies to DOM elements (string tags). When wrapping React components, all props are forwarded.

Default Prop Filtering

For DOM elements without custom shouldForwardProp:

Class Name Merging

User-provided className is merged with the generated class:

<Box className="extra">Hello</Box>
// Renders: <div class="vl-abc123 extra">Hello</div>

Specificity Boost

Double the selector to raise specificity from (0,1,0) to (0,2,0):

const Override = styled('div', { boost: true })`
  color: red;
`
// Generates: .vl-abc.vl-abc { color: red; }
// Overrides inner library components regardless of CSS source order

Static vs Dynamic Paths

The engine automatically detects whether a template has dynamic interpolations and uses the optimal path:

Static Path

When no interpolation values are functions (or nested CSSResults containing functions):

1. CSS resolved once at component creation time (module evaluation)
2. Class name computed and CSS injected immediately
3. Zero per-render overhead — no theme context access, no resolution
4. Component simply applies the pre-computed class name

// Static — class computed once, shared across all instances
const Box = styled.div`
  padding: 16px;
  margin: 8px;
  background: white;
`

Dynamic Path

When any interpolation is a function:

1. Theme accessed via useTheme() on every render
2. CSS resolved with { ...componentProps, theme }
3. useRef cache — CSS string comparison avoids rehashing when content unchanged
4. useInsertionEffect injects CSS synchronously before paint
5. Dedup cache prevents duplicate style injection

// Dynamic — resolved per render, cached by CSS string comparison
const Box = styled.div`
  padding: ${(props) => props.$p}px;
  color: ${(props) => props.theme.colors.primary};
`

keyframes()

Create CSS @keyframes animations. Injection is synchronous and immediate.

import { keyframes, styled } from '@vitus-labs/styler'

const fadeIn = keyframes`
  from { opacity: 0; transform: translateY(-10px); }
  to { opacity: 1; transform: translateY(0); }
`

const FadeInBox = styled.div`
  animation: ${fadeIn} 0.3s ease-in-out;
`

Behavior

• Returns a KeyframesResult with a .name property (vl-kf-<hash>)
• String coercion returns the animation name for use in CSS interpolations
• Deterministic naming via FNV-1a hash of the CSS body
• No dynamic interpolations — keyframes are always static
• Injected as @keyframes vl-kf-<hash> { ... } into the global sheet
• Deduplicated by animation name

createGlobalStyle()

Inject unscoped global CSS. Returns a React component.

import { createGlobalStyle } from '@vitus-labs/styler'

const GlobalStyles = createGlobalStyle`
  * {
    box-sizing: border-box;
    margin: 0;
  }

  body {
    font-family: system-ui, sans-serif;
    background: ${(props) => props.theme?.background || '#fff'};
  }
`

function App() {
  return (
    <>
      <GlobalStyles />
      <Main />
    </>
  )
}

Behavior

• Returns a React component (not a CSSResult)
• Component props are merged with theme for interpolation resolution
• Unscoped — CSS injected without any .vl-* class wrapper
• Static path: CSS resolved once at creation, component renders nothing on client
• Dynamic path: CSS resolved per render, injected via useInsertionEffect
• SSR: Renders <style precedence="low"> — lower precedence than component styles (medium)
• Deduplicated by hash of resolved CSS

useCSS()

Hook that resolves a CSSResult to a class name string. Use when you need styling without creating a styled component wrapper.

import { css, useCSS } from '@vitus-labs/styler'

const highlight = css`
  color: red;
  font-weight: bold;
`

function Label({ children }) {
  const className = useCSS(highlight)
  return <span className={className}>{children}</span>
}

Signature

useCSS(
  template: CSSResult,
  props?: Record<string, any>,
  boost?: boolean
): string  // class name

Dynamic Styles

const badge = css`
  background: ${(props) => props.variant === 'success' ? 'green' : 'gray'};
  padding: 4px 8px;
  border-radius: 4px;
`

function Badge({ variant, children }) {
  const className = useCSS(badge, { variant })
  return <span className={className}>{children}</span>
}

Theme is automatically merged from context. Same caching and injection mechanism as styled().

CSS Nesting

Native CSS nesting with & selectors is fully supported:

const Card = styled.div`
  background: white;
  padding: 16px;

  & h2 {
    margin-bottom: 8px;
    font-size: 1.5rem;
  }

  & p {
    color: #666;
  }

  &:hover {
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  }

  &.active {
    border-color: blue;
  }
`

At-Rule Splitting

@media, @supports, and @container at-rules are automatically extracted from the CSS body and emitted as separate top-level rules with the selector wrapped inside. This works around CSSOM spec limitations:

const Responsive = styled.div`
  font-size: 14px;
  @media (min-width: 600px) {
    font-size: 18px;
  }
`
// Emits two rules:
// .vl-abc { font-size: 14px; }
// @media (min-width: 600px) { .vl-abc { font-size: 18px; } }

Non-splittable at-rules (@keyframes, @font-face) are left in place.

Deduplication & Caching

• Same CSS always produces the same FNV-1a hash → same class name
• If two components generate identical CSS, the rule is injected once and both share the class name
• Dynamic path uses a useRef cache per component instance — string comparison skips rehashing when CSS unchanged between renders
• Global StyleSheet cache bounded by maxCacheSize (default 10,000) with 10% eviction on overflow

HMR Support

For development with hot module replacement:

import { sheet } from '@vitus-labs/styler'

if (import.meta.hot) {
  import.meta.hot.accept(() => {
    sheet.clearAll()  // Purge all cached + injected styles
  })
}

• sheet.clearCache() — Clears the dedup cache plus the resolve-side caches (insertCache, prepareCache, normCache). Keeps the already-injected CSS in the DOM. Useful for HMR scenarios where you want to recompute classes but not flush rules.
• sheet.clearAll() — Clears everything clearCache() does, plus the SSR buffer, plus removes all rules from the DOM. Also fires registered clearCallbacks so consumers like styled.ts reset their staticComponentCache and hotCache. Use for full HMR resets.

Benchmarks

All benchmarks run via Vitest bench. React is externalized in all bundle measurements.

Bundle Size

styler beats styled-components by 45% and Emotion by 40% while supporting React 19 SSR, @layer wrapping, @media/@supports/@container rule splitting, specificity boost, theming, global styles, keyframes, and multi-tier render caching.

What's in the bundle

For a CSS-in-JS engine that ships SSR + bundler-style features, ~10 KB gzipped is the realistic floor. The size is driven by these source modules:

If you're optimizing for the smallest possible bundle and don't need SSR or the full HTML attribute filter, goober at 1.31 KB is the minimal-feature option. styler's value is the feature set per kilobyte.

Performance (ops/sec, higher is better)

Styler is 2.8–1034x faster than alternatives across css creation, composition, and SSR. The styled() factory is essentially tied with goober (17.3M vs 18.2M ops/s) while being 158x faster than styled-components and 18x faster than Emotion. The only benchmark where styler doesn't lead is dynamic function interpolation, where styled-components' manual flatten is ~8% faster.