Connectors

Connectors are adapter packages that standardize how different CSS-in-JS libraries integrate with the Vitus Labs UI System. They allow switching between CSS engines without changing component code.

Why Connectors?

All vitus-labs components depend on @vitus-labs/core, not on a specific CSS-in-JS library. The connector system:

1. Decouples components from CSS engines — write once, run with any supported engine
2. Provides a unified interface — all connectors implement the same CSSEngineConnector shape
3. Enables runtime engine selection — call init() at startup to choose your engine
4. Supports lazy initialization — destructured functions work before init() is called

CSSEngineConnector Interface

Every connector exports these functions:

Available Connectors

connector-styler (Recommended)

Uses the built-in @vitus-labs/styler engine. Lightweight (~3KB gzipped), purpose-built for the UI system.

npm install @vitus-labs/connector-styler

import { init } from '@vitus-labs/core'
import {
  css,
  styled,
  provider,
  keyframes,
  createGlobalStyle,
  useTheme,
} from '@vitus-labs/connector-styler'

init({ css, styled, provider, keyframes, createGlobalStyle, useTheme })

Implementation: Pure pass-through — re-exports @vitus-labs/styler functions directly.

connector-styled-components

Uses styled-components (v6+) for applications already using it.

npm install @vitus-labs/connector-styled-components

import { init } from '@vitus-labs/core'
import {
  css,
  styled,
  provider,
  keyframes,
  createGlobalStyle,
  useTheme,
} from '@vitus-labs/connector-styled-components'

init({ css, styled, provider, keyframes, createGlobalStyle, useTheme })

Implementation: Pure pass-through — re-exports styled-components functions directly.

Peer dependency: styled-components >= 6

connector-emotion

Uses @emotion/react + @emotion/styled with an adapter layer for CSS composition compatibility.

npm install @vitus-labs/connector-emotion

import { init } from '@vitus-labs/core'
import {
  css,
  styled,
  provider,
  keyframes,
  createGlobalStyle,
  useTheme,
} from '@vitus-labs/connector-emotion'

init({ css, styled, provider, keyframes, createGlobalStyle, useTheme })

Implementation: Adapter wrapping Emotion's APIs to match styled-components' CSS composition pattern.

The adapter handles:

• Static templates → returns plain string (fast path, no overhead)
• Static values (all interpolations are strings/numbers) → builds string directly (second fast path)
• Dynamic templates (with function interpolations) → returns (props) => string thunk that Emotion's styled resolves at render time
• createGlobalStyle → wraps Emotion's <Global> component to match the styled-components API

Internally, the adapter uses a resolveValue() helper that recursively resolves interpolation values:

• null/false/true → empty string
• Functions → called with props, then recursed
• Arrays → each element recursed and joined
• Primitives → converted to string

Peer dependencies: @emotion/react >= 11, @emotion/styled >= 11

How init() Works

The init() function from @vitus-labs/core registers the CSS engine:

import { init } from '@vitus-labs/core'

init({
  css,              // Required: tagged template for CSS fragments
  styled,           // Required: component factory
  provider,         // Required: ThemeProvider
  keyframes,        // Optional: keyframe animations
  createGlobalStyle, // Optional: global styles
  useTheme,         // Optional: theme hook
})

Lazy Delegate Pattern

The core uses a lazy delegate pattern, so you can destructure config at module level before init() is called:

import { config } from '@vitus-labs/core'

// These work even before init() — they delegate to the engine when called
const { styled, css } = config

// Later, in your app entry:
init({ css: engineCss, styled: engineStyled, provider: engineProvider })

// Now all styled/css calls from any module use the registered engine

Choosing a Connector

Web Connector Compatibility

All web connectors support:

• CSS-in-CSS nesting (tagged template composition)
• Dynamic interpolations (functions receiving props)
• Theme context via provider
• Keyframes and global styles

React Native

For React Native, use connector-native which parses CSS template literals into style objects instead of generating CSS class names. See the dedicated React Native connector page for details.

Switching Engines

To switch engines, just change the import and reinstall dependencies:

// Before: styled-components
import * as connector from '@vitus-labs/connector-styled-components'

// After: styler
import * as connector from '@vitus-labs/connector-styler'

// Same init call
init(connector)

No component code changes required.

API Reference

CSSEngineConnector