{"id":11706,"library":"react-fela","title":"React Fela Bindings","description":"react-fela provides the official React bindings for the Fela dynamic styling library. It facilitates CSS-in-JS styling within React applications, leveraging Fela's core capabilities for atomic CSS generation, performance optimization, and server-side rendering. The current stable version is 12.2.1, with a consistent release cadence that includes minor feature additions, TypeScript improvements, and bug fixes across patch versions. Key differentiators include its focus on a functional, atomic CSS approach, robust plugin system (enhanced with context-free plugins in v12), and efficient rehydration mechanisms. It assumes familiarity with the core Fela library for its effective use within a React ecosystem.","status":"active","version":"12.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/robinweser/fela","tags":["javascript","fela","dynamic styling","react","css","styling","cssinjs","typescript"],"install":[{"cmd":"npm install react-fela","lang":"bash","label":"npm"},{"cmd":"yarn add react-fela","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-fela","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Fela renderer library required for all Fela operations.","package":"fela","optional":false},{"reason":"React framework is required as this package provides React bindings.","package":"react","optional":false}],"imports":[{"note":"A named export hook for functional components to access the renderer and theme context. Used extensively in modern React Fela applications.","wrong":"import useFela from 'react-fela'","symbol":"useFela","correct":"import { useFela } from 'react-fela'"},{"note":"Required to provide the Fela renderer instance to the entire React component tree. CommonJS `require` is generally discouraged due to ecosystem shift to ESM.","wrong":"const { RendererProvider } = require('react-fela')","symbol":"RendererProvider","correct":"import { RendererProvider } from 'react-fela'"},{"note":"Used to pass a theme object down the React tree via context. While aliasing is not inherently wrong, it's not the default usage.","wrong":"import { ThemeProvider as FelaThemeProvider } from 'react-fela'","symbol":"ThemeProvider","correct":"import { ThemeProvider } from 'react-fela'"},{"note":"The `createRenderer` function comes directly from the core `fela` package, not `react-fela` itself. This is a common mis-import.","wrong":"import { createRenderer } from 'react-fela'","symbol":"createRenderer","correct":"import { createRenderer } from 'fela'"}],"quickstart":{"code":"import { createRenderer } from 'fela';\nimport { RendererProvider, ThemeProvider, useFela } from 'react-fela';\nimport { useState } from 'react';\n\nconst renderer = createRenderer();\n\nconst theme = {\n  primary: 'blue',\n  secondary: 'green',\n  spacing: 16,\n};\n\ntype ButtonProps = {\n  onClick: () => void;\n  children: React.ReactNode;\n};\n\nconst Button: React.FC<ButtonProps> = ({ onClick, children }) => {\n  const { css } = useFela((props: { primaryColor: string }) => ({\n    button: {\n      backgroundColor: props.primaryColor,\n      color: 'white',\n      padding: `${theme.spacing / 2}px ${theme.spacing}px`,\n      borderRadius: '4px',\n      border: 'none',\n      cursor: 'pointer',\n      fontSize: '16px',\n      '&:hover': {\n        opacity: 0.8,\n      },\n    },\n  }));\n\n  return (\n    <button className={css('button', { primaryColor: theme.primary })} onClick={onClick}>\n      {children}\n    </button>\n  );\n};\n\nconst App: React.FC = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <RendererProvider renderer={renderer}>\n      <ThemeProvider theme={theme}>\n        <div style={{ fontFamily: 'sans-serif', padding: theme.spacing }}>\n          <h1>Fela with React Example</h1>\n          <p>Count: {count}</p>\n          <Button onClick={() => setCount(prev => prev + 1)}>Increment</Button>\n          <div className={useFela(() => ({\n            marginTop: theme.spacing,\n            color: theme.secondary,\n            fontSize: '14px'\n          }))().css({})}>\n            Styled with `useFela` hook directly on a div.\n          </div>\n        </div>\n      </ThemeProvider>\n    </RendererProvider>\n  );\n};\n\nexport default App;","lang":"typescript","description":"This quickstart demonstrates the basic setup of Fela with React using the `useFela` hook, `RendererProvider`, and `ThemeProvider` to apply dynamic styles and theme values in a functional component."},"warnings":[{"fix":"Consult the official Fela v12 migration guide (fela.js.org/docs/latest/extra/migration) for detailed steps and necessary code adjustments.","message":"Fela v12 introduced significant architectural changes, including a new context-free plugin concept and rehydration improvements. This requires migration for applications upgrading from Fela v11 or earlier.","severity":"breaking","affected_versions":">=12.0.0"},{"fix":"Upgrade to `react-fela@12.0.1` or higher to resolve the accidental `theme` attribute passing.","message":"Fela v12.0.0 had a bug that accidentally passed an extra `theme` attribute to elements, potentially causing unexpected behavior or rendering issues. This was addressed in a hotfix.","severity":"gotcha","affected_versions":"12.0.0"},{"fix":"Upgrade to `react-fela@11.6.0` or higher to remove this restriction, or ensure `RendererProvider` only wraps a single child element (e.g., a `Fragment` or `div`).","message":"Prior to Fela v11.6.0, the `RendererProvider` component had a `Children.only` restriction, meaning it could only accept a single child. This could lead to runtime errors if multiple children were provided.","severity":"breaking","affected_versions":"<11.6.0"},{"fix":"Run `npm install fela` or `yarn add fela` and verify its version matches the peer dependency requirement in `react-fela`'s `package.json`.","message":"Ensure `fela` is installed as a direct dependency or peer dependency that satisfies the `react-fela` version requirements. `react-fela` provides bindings, but the core Fela library is essential for styling to function.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Wrap your root component or the section using Fela styles with `<RendererProvider renderer={myRendererInstance}>...</RendererProvider>`.","cause":"The Fela renderer instance was not provided to the React component tree via the `RendererProvider`.","error":"Error: Fela renderer not found. Make sure to wrap your application with `RendererProvider`."},{"fix":"Ensure your components are wrapped with `<ThemeProvider theme={myThemeObject}>...</ThemeProvider>` and that `myThemeObject` is a valid theme object.","cause":"A component attempted to access `theme` from the Fela context, but `ThemeProvider` was not used or the theme object was not provided.","error":"TypeError: Cannot read properties of undefined (reading 'theme')"},{"fix":"Install the core Fela package by running `npm install fela` or `yarn add fela`.","cause":"The core `fela` package, a peer dependency of `react-fela`, is not installed or cannot be resolved by the module bundler.","error":"Module not found: Can't resolve 'fela' in '.../node_modules/react-fela/lib'"}],"ecosystem":"npm"}