React Fela Bindings

Common errors

• Error: Fela renderer not found. Make sure to wrap your application with `RendererProvider`.

  cause The Fela renderer instance was not provided to the React component tree via the `RendererProvider`.
  fix Wrap your root component or the section using Fela styles with `<RendererProvider renderer={myRendererInstance}>...</RendererProvider>`.

• TypeError: Cannot read properties of undefined (reading 'theme')

  cause A component attempted to access `theme` from the Fela context, but `ThemeProvider` was not used or the theme object was not provided.
  fix Ensure your components are wrapped with `<ThemeProvider theme={myThemeObject}>...</ThemeProvider>` and that `myThemeObject` is a valid theme object.

• Module not found: Can't resolve 'fela' in '.../node_modules/react-fela/lib'

  cause The core `fela` package, a peer dependency of `react-fela`, is not installed or cannot be resolved by the module bundler.
  fix Install the core Fela package by running `npm install fela` or `yarn add fela`.

Warnings

• breaking 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.
  Fix: Consult the official Fela v12 migration guide (fela.js.org/docs/latest/extra/migration) for detailed steps and necessary code adjustments.
• gotcha 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.
  Fix: Upgrade to `react-fela@12.0.1` or higher to resolve the accidental `theme` attribute passing.
• breaking 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.
  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`).
• gotcha 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.
  Fix: Run `npm install fela` or `yarn add fela` and verify its version matches the peer dependency requirement in `react-fela`'s `package.json`.

Install

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

Imports

• useFela
  wrong:

  import useFela from 'react-fela'

  correct:

  import { useFela } from 'react-fela'

  A named export hook for functional components to access the renderer and theme context. Used extensively in modern React Fela applications.
• RendererProvider
  wrong:

  const { RendererProvider } = require('react-fela')

  correct:

  import { RendererProvider } from 'react-fela'

  Required to provide the Fela renderer instance to the entire React component tree. CommonJS `require` is generally discouraged due to ecosystem shift to ESM.
• ThemeProvider
  wrong:

  import { ThemeProvider as FelaThemeProvider } from 'react-fela'

  correct:

  import { ThemeProvider } from 'react-fela'

  Used to pass a theme object down the React tree via context. While aliasing is not inherently wrong, it's not the default usage.
• createRenderer
  wrong:

  import { createRenderer } from 'react-fela'

  correct:

  import { createRenderer } from 'fela'

  The `createRenderer` function comes directly from the core `fela` package, not `react-fela` itself. This is a common mis-import.

Quickstart

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.

import { createRenderer } from 'fela';
import { RendererProvider, ThemeProvider, useFela } from 'react-fela';
import { useState } from 'react';

const renderer = createRenderer();

const theme = {
  primary: 'blue',
  secondary: 'green',
  spacing: 16,
};

type ButtonProps = {
  onClick: () => void;
  children: React.ReactNode;
};

const Button: React.FC<ButtonProps> = ({ onClick, children }) => {
  const { css } = useFela((props: { primaryColor: string }) => ({
    button: {
      backgroundColor: props.primaryColor,
      color: 'white',
      padding: `${theme.spacing / 2}px ${theme.spacing}px`,
      borderRadius: '4px',
      border: 'none',
      cursor: 'pointer',
      fontSize: '16px',
      '&:hover': {
        opacity: 0.8,
      },
    },
  }));

  return (
    <button className={css('button', { primaryColor: theme.primary })} onClick={onClick}>
      {children}
    </button>
  );
};

const App: React.FC = () => {
  const [count, setCount] = useState(0);

  return (
    <RendererProvider renderer={renderer}>
      <ThemeProvider theme={theme}>
        <div style={{ fontFamily: 'sans-serif', padding: theme.spacing }}>
          <h1>Fela with React Example</h1>
          <p>Count: {count}</p>
          <Button onClick={() => setCount(prev => prev + 1)}>Increment</Button>
          <div className={useFela(() => ({
            marginTop: theme.spacing,
            color: theme.secondary,
            fontSize: '14px'
          }))().css({})}>
            Styled with `useFela` hook directly on a div.
          </div>
        </div>
      </ThemeProvider>
    </RendererProvider>
  );
};

export default App;