@axiom-core/react-adapter

The official Axiom Design System adapter for React. Connects @axiom-core/runtime-engine resolved themes to React applications by providing a context provider, deterministic CSS variable injection, and reactive theme updates.

Responsibilities

• Context provider — exposes the current resolved theme to the React component tree via AxiomContext
• CSS variable injection — emits deterministic CSS custom properties into the DOM using @axiom-core/css-bridge and @axiom-core/dom-injector
• Reactive theme updates — subscribes to the theme manager and triggers re-injection when the resolved theme changes
• SSR support — renders a <style> tag on the server via @axiom-core/ssr-utils for hydration-safe style delivery

This package does not contain runtime composition logic. Theme composition is handled by @axiom-core/runtime-engine.

Installation

pnpm add @axiom-core/runtime-engine
pnpm add @axiom-core/react-adapter

React and ReactDOM are peer dependencies:

pnpm add react react-dom

Usage

Base Entry — Pre-Resolved Theme

Use the base entry when you have a pre-resolved theme (e.g., statically exported JSON) and do not need runtime axis switching:

import { AxiomProvider } from '@axiom-core/react-adapter';

const resolvedTheme = { /* your pre-resolved theme */ };

function App() {
  return (
    <AxiomProvider resolvedTheme={resolvedTheme} scope="global">
      <YourApp />
    </AxiomProvider>
  );
}

Runtime Entry — Dynamic Theme Composition

Use the runtime entry when you need dynamic axis switching (e.g., light/dark mode toggle, brand switching, density control):

import { AxiomProvider } from '@axiom-core/react-adapter/runtime';
import { createThemeManager } from '@axiom-core/runtime-engine';
import { enterprisePrimitives } from '@axiom-core/primitives';
import { baseSemantic, semanticAxes } from '@axiom-core/semantic-baseline';

const manager = createThemeManager({
  primitives: enterprisePrimitives,
  baseSemantic,
  registry: semanticAxes,
  initialConfig: { mode: 'light' },
});

function App() {
  return (
    <AxiomProvider manager={manager}>
      <YourApp />
    </AxiomProvider>
  );
}

Switching Axes at Runtime

import { useAxiomContext } from '@axiom-core/react-adapter';

function ThemeToggle() {
  const { updateAxis } = useAxiomContext();

  return (
    <button onClick={() => updateAxis('mode', 'dark')}>
      Switch to Dark Mode
    </button>
  );
}

Variable Name Modes

Axiom supports two CSS variable naming modes that control how custom property names are generated:

| Mode | Variable Format | Use Case | |---|---|---| | dev | --axiom-surface-background | Human-readable names. Easier to debug in browser DevTools. | | prod | --ax-a1b2c3 | Hashed names. Shorter, obfuscated, minimal bundle impact. |

The CSS variable values are identical in both modes. Only the property names differ. The golden hash validation enforces that the same theme input always produces the same variable names in the same mode.

Set the mode on the provider:

<AxiomProvider manager={manager} mode="prod">
  <App />
</AxiomProvider>

The default mode is dev in development environments and prod in production.

Context API

useAxiomContext()

Returns the Axiom context for the nearest AxiomProvider ancestor.

import { useAxiomContext } from '@axiom-core/react-adapter';

function MyComponent() {
  const { resolvedTheme, config, updateAxis } = useAxiomContext();

  // resolvedTheme: ResolvedSemanticTokens — current fully resolved theme
  // config: ThemeConfig — current axis configuration { mode, brand, ... }
  // updateAxis: (axis: ThemeAxis, value: string) => void — update a single axis

  return <div style={{ color: resolvedTheme.content?.primary as string }} />;
}

Returned Properties

| Property | Type | Description | |---|---|---| | resolvedTheme | ResolvedSemanticTokens | The currently resolved theme. All token references replaced with primitive values. | | config | ThemeConfig | The active axis configuration. | | updateAxis | (axis: ThemeAxis, value: string) => void | Updates a single axis (e.g., 'mode', 'brand') and triggers re-injection. |

SSR Support

react-adapter is fully compatible with server-side rendering. On the server, use renderAxiomStyles from @axiom-core/ssr-utils (re-exported for convenience) to produce a <style> tag that can be injected into the server-rendered HTML:

import { renderAxiomStyles } from '@axiom-core/react-adapter';

// On the server, before rendering
const { cssText, attributes } = renderAxiomStyles({
  resolvedTheme,
  mode: 'prod',
  scope: 'global',
});

const html = `
<!DOCTYPE html>
<html>
  <head>
    <style id="axiom-ssr">${cssText}</style>
  </head>
  <body>
    ${appHtml}
  </body>
</html>
`;

On hydration, the client-side provider detects the existing SSR style tag and skips the initial injection to avoid a flash of unstyled content.

Bundle Entries

| Import Path | Contents | When to Use | |---|---|---| | @axiom-core/react-adapter | Provider + context + hooks (no runtime engine) | Pre-resolved themes | | @axiom-core/react-adapter/runtime | Above + AxiomProviderRuntime component | Dynamic theme composition |

Peer Dependencies

| Package | Version | |---|---| | react | >=18 | | react-dom | >=18 | | @axiom-core/runtime-engine | >=0.1.0 (optional — only for runtime entry) | | @axiom-core/core-engine | >=0.1.0 (optional — only for runtime entry) |

License

MIT