Registry / web-framework / styletron-react

styletron-react

JSON →
library6.1.1jsnpmunverified

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.

npm install styletron-react
INSTALL
IMPORT
SIG · STYLETRON-REACT
S
styletron-react
web-frameworkjavascriptv6.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

styled
import { styled } from 'styletron-react';
const styled = require('styletron-react').styled;
The primary function for creating styled React components. CommonJS `require` is not officially supported for this export.
useStyletron
import { useStyletron } from 'styletron-react';
const useStyletron = require('styletron-react').useStyletron;
Introduced in v5, this hook allows direct CSS class generation for functional components without `styled`. Requires React 16.8+.
StyletronProvider
import { StyletronProvider } from 'styletron-react';
import StyletronProvider from 'styletron-react/provider';
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.

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'));
Debug
Known issues
breakingStyletron-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.
affects: >=5.0.0
breakingIn 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`.
affects: >=5.0.0
gotchaStyletron-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' }))`).
affects: >=4.0.0
gotchaAvoid 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.
affects: >=4.0.0
Errors
Common errors & fixes
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?
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.
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.
Upgrade
Version history
6.1.1latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React functionality.
styletron-engine-atomicoptionalCommonly used atomic CSS engine. Required for most client-side setups.
Agent activity
2 hits · last 30 days
node
2
Resources