{"id":12099,"library":"styletron-react","title":"Styletron React Bindings","description":"Styletron-react (current version 6.1.1) provides React bindings for Styletron, a universal, high-performance CSS-in-JS engine. It streamlines styling in React applications by offering an API inspired by `styled-components` but primarily uses JavaScript objects for styles instead of template strings. Key differentiators include its \"atomic CSS\" approach, which generates highly optimized, declaration-level deduplicated CSS, minimizing bundle size and improving critical rendering path performance for server-rendered pages. It also boasts efficient client-side style injection with hyper-granular memoization and fast cache hydration. Styletron aims to eliminate global namespace concerns, simplify dependencies, and handle dead code elimination and minification effectively, requiring no extra tooling beyond npm. The library is actively maintained, with a typical release cycle of around 34 days, as seen in broader Styletron comparisons. It supports both traditional styled components and a `useStyletron` hook for flexible, performant styling.","status":"active","version":"6.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/styletron/styletron","tags":["javascript","typescript"],"install":[{"cmd":"npm install styletron-react","lang":"bash","label":"npm"},{"cmd":"yarn add styletron-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add styletron-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React functionality.","package":"react","optional":false},{"reason":"Commonly used atomic CSS engine. Required for most client-side setups.","package":"styletron-engine-atomic","optional":true}],"imports":[{"note":"The primary function for creating styled React components. CommonJS `require` is not officially supported for this export.","wrong":"const styled = require('styletron-react').styled;","symbol":"styled","correct":"import { styled } from 'styletron-react';"},{"note":"Introduced in v5, this hook allows direct CSS class generation for functional components without `styled`. Requires React 16.8+.","wrong":"const useStyletron = require('styletron-react').useStyletron;","symbol":"useStyletron","correct":"import { useStyletron } from 'styletron-react';"},{"note":"Provides the Styletron engine instance to the React component tree via context. Often aliased as `Provider`.","wrong":"import StyletronProvider from 'styletron-react/provider';","symbol":"StyletronProvider","correct":"import { StyletronProvider } from 'styletron-react';"},{"note":"Optional import for a development-only debug engine, useful for inspecting styles during development.","symbol":"DebugEngine","correct":"import { DebugEngine } from 'styletron-react';"}],"quickstart":{"code":"import * as React from 'react';\nimport { render } from 'react-dom';\nimport { Provider as StyletronProvider, styled, useStyletron, DebugEngine } from 'styletron-react';\nimport { Client as Styletron } from 'styletron-engine-atomic';\n\n// 1. Create a client engine instance\nconst engine = new Styletron();\n\n// 2. Create a debug engine instance for development\nconst debug = process.env.NODE_ENV === 'production' ? null : new DebugEngine();\n\n// 3. Create a styled component\nconst RedText = styled('span', {\n  color: 'red',\n  fontSize: '24px',\n  fontWeight: 'bold',\n  ':hover': {\n    color: 'darkred'\n  }\n});\n\n// 4. Create a functional component using the hook\nfunction MyHookComponent() {\n  const [css] = useStyletron();\n  const dynamicColor = Math.random() > 0.5 ? 'blue' : 'green';\n  return (\n    <p className={css({\n      color: dynamicColor,\n      fontSize: '18px',\n      padding: '8px',\n      backgroundColor: 'lightgray',\n      borderRadius: '4px'\n    })}>\n      This text is styled with the useStyletron hook and has a {dynamicColor} color.\n    </p>\n  );\n}\n\n// 5. Wrap your application with the StyletronProvider\nfunction App() {\n  return (\n    <StyletronProvider value={engine} debug={debug}>\n      <div>\n        <h1>Welcome to Styletron!</h1>\n        <RedText>This is a styled component.</RedText>\n        <MyHookComponent />\n        <p>\n          Styletron provides high-performance, atomic CSS-in-JS solutions,\n          optimizing CSS delivery and bundle size by de-duplicating styles.\n        </p>\n      </div>\n    </StyletronProvider>\n  );\n}\n\nrender(<App />, document.getElementById('root'));\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your `react` and `react-dom` packages to version `16.8.0` or newer.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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' }))`).","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"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?"},{"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.","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.","error":"Warning: React does not recognize the $somePropName prop on a DOM element."}],"ecosystem":"npm"}