Styletron React Bindings

Common errors

• Error: A Styletron styled component was rendered, but no Styletron engine instance was provided in React context. Did you forget to provide a Styletron engine instance to React context via using the Styletron provider component?

  cause The `StyletronProvider` component (or its alias) was not rendered at a high enough level in the component tree, or multiple instances of `styletron-react` exist in `node_modules` causing a context mismatch.
  fix Ensure your entire React application is wrapped by `StyletronProvider` and that you pass a valid `styletron-engine` instance (e.g., `new Client()`) to its `value` prop. Verify there are no duplicate `styletron-react` packages in your dependency tree.

• Warning: React does not recognize the $somePropName prop on a DOM element.

  cause A prop prefixed with `$` was inadvertently passed to a native DOM element (like `<div>` or `<span>`) instead of being consumed by the `styled` component or `useStyletron` hook.
  fix This warning indicates that Styletron's prop filtering is working as intended. Ensure that `$somePropName` is only used for styling or internal logic within your styled component or hook, and is not passed explicitly to the underlying DOM element. If you see this, it implies React did not recognize the prop you intended to filter.

Warnings

• breaking Styletron-react v5.0.0 and later require React version 16.8.0 or higher due to the introduction of React Hooks, specifically the `useStyletron` hook. Ensure your React dependency meets this minimum requirement.
  Fix: Upgrade your `react` and `react-dom` packages to version `16.8.0` or newer.
• breaking In v5.0.0, the original `withStyle` functionality was replaced by `withStyleDeep`. While `withStyle` is temporarily aliased to `withStyleDeep` for backward compatibility, its behavior changed to deep merging styles. Additionally, the `$ref` prop was removed in favor of standard React `ref` forwarding.
  Fix: Review existing `withStyle` usages for unintended deep merging effects. Replace all instances of `$ref` with the standard `ref` prop and ensure components correctly use `React.forwardRef`.
• gotcha Styletron-react filters out props prefixed with `$` (e.g., `$isActive`, `$theme`) so they are not passed down to the underlying DOM element, preventing React warnings about unknown DOM attributes. Remember to prefix your custom props if they are used solely for styling or internal logic and should not appear on the DOM element.
  Fix: Prefix any props intended for internal styling or logic (and not meant for the DOM) with a `$` (e.g., `styled('div', props => ({ color: props.$isActive ? 'blue' : 'black' }))`).
• gotcha Avoid mixing shorthand and longhand CSS properties within the same style object for a single `styled` component or `useStyletron` call. Due to Styletron's atomic CSS approach and JavaScript object property iteration order, this can lead to non-deterministic styling outcomes.
  Fix: Consistently use either shorthand or longhand properties for a given CSS feature (e.g., use `borderWidth`, `borderStyle`, `borderColor` or just `border`, but not both `border` and `borderWidth` in the same style object). If using `styletron-engine-monolithic`, this restriction is relaxed.

Install

• npm install styletron-react npm
• yarn add styletron-react yarn
• pnpm add styletron-react pnpm

Imports

• styled
  wrong:

  const styled = require('styletron-react').styled;

  correct:

  import { styled } from 'styletron-react';

  The primary function for creating styled React components. CommonJS `require` is not officially supported for this export.
• useStyletron
  wrong:

  const useStyletron = require('styletron-react').useStyletron;

  correct:

  import { useStyletron } from 'styletron-react';

  Introduced in v5, this hook allows direct CSS class generation for functional components without `styled`. Requires React 16.8+.
• StyletronProvider
  wrong:

  import StyletronProvider from 'styletron-react/provider';

  correct:

  import { StyletronProvider } from 'styletron-react';

  Provides the Styletron engine instance to the React component tree via context. Often aliased as `Provider`.
• DebugEngine

  import { DebugEngine } from 'styletron-react';

  Optional import for a development-only debug engine, useful for inspecting styles during development.

Quickstart

This example demonstrates how to set up Styletron with `styletron-react`, including creating a client engine, using both the `styled` factory for component-based styling, and the `useStyletron` hook for dynamic, inline-style-like class generation.

import * as React from 'react';
import { render } from 'react-dom';
import { Provider as StyletronProvider, styled, useStyletron, DebugEngine } from 'styletron-react';
import { Client as Styletron } from 'styletron-engine-atomic';

// 1. Create a client engine instance
const engine = new Styletron();

// 2. Create a debug engine instance for development
const debug = process.env.NODE_ENV === 'production' ? null : new DebugEngine();

// 3. Create a styled component
const RedText = styled('span', {
  color: 'red',
  fontSize: '24px',
  fontWeight: 'bold',
  ':hover': {
    color: 'darkred'
  }
});

// 4. Create a functional component using the hook
function MyHookComponent() {
  const [css] = useStyletron();
  const dynamicColor = Math.random() > 0.5 ? 'blue' : 'green';
  return (
    <p className={css({
      color: dynamicColor,
      fontSize: '18px',
      padding: '8px',
      backgroundColor: 'lightgray',
      borderRadius: '4px'
    })}>
      This text is styled with the useStyletron hook and has a {dynamicColor} color.
    </p>
  );
}

// 5. Wrap your application with the StyletronProvider
function App() {
  return (
    <StyletronProvider value={engine} debug={debug}>
      <div>
        <h1>Welcome to Styletron!</h1>
        <RedText>This is a styled component.</RedText>
        <MyHookComponent />
        <p>
          Styletron provides high-performance, atomic CSS-in-JS solutions,
          optimizing CSS delivery and bundle size by de-duplicating styles.
        </p>
      </div>
    </StyletronProvider>
  );
}

render(<App />, document.getElementById('root'));