TSS-React: Type-Safe CSS-in-JS with Emotion

Common errors

• TypeError: Cannot read properties of undefined (reading 'main') (or similar theme property access error)

  cause The theme object is not being correctly provided to `tss-react` via Emotion's `ThemeProvider`, or the theme structure is different than expected.
  fix Ensure your component tree is wrapped with `import { ThemeProvider } from '@emotion/react';` and that a valid theme object is passed to it. If using Material UI, ensure the MUI theme is also accessible to Emotion's context.

• Error: Invalid hook call. Hooks can only be called inside of the body of a functional component.

  cause The `makeStyles` or `useStyles` hook is being called outside of a React functional component or custom hook context.
  fix Ensure `makeStyles` is called at the module level to create your `useStyles` hook, and that the `useStyles` hook itself is called within a functional component or another custom hook.

• Cannot find module 'tss-react' or its corresponding type declarations.

  cause The package is not installed, or there's a problem with module resolution in your build system (e.g., incorrect `paths` in `tsconfig.json`, or a CJS/ESM mismatch).
  fix Run `npm install tss-react` or `yarn add tss-react`. For TypeScript, ensure your `tsconfig.json` targets a modern module system like `esnext` and check `moduleResolution` settings. Avoid `require()` for importing tss-react.

• Type 'Classes' is not assignable to type 'string | undefined'. Property 'root' is missing in type 'Classes'.

  cause A type-checking error indicating that your style definition is incomplete or incorrect, or you are trying to use a class name that hasn't been defined in your `makeStyles` object.
  fix Verify that all class names you are trying to use (e.g., `classes.root`) are actually defined as keys in the object returned by your `makeStyles` function. Ensure your styles object adheres to the expected CSS properties and types.

Warnings

• gotcha tss-react does not support React Server Components (RSC) in Next.js. Dynamic style generation, a core feature, is incompatible with the RSC paradigm. Users needing RSC support should consider zero-runtime CSS solutions.
  Fix: For RSC environments, consider alternative zero-runtime CSS-in-JS solutions like Panda-CSS or Vanilla Extract, or utilize traditional CSS modules/global stylesheets.
• breaking The `makeStyles` API expects a theme object to be provided via `@emotion/react`'s `ThemeProvider`. If `tss-react` is used alongside `@mui/material`, ensure both Material UI's `ThemeProvider` and Emotion's `ThemeProvider` are correctly configured, typically wrapping the Material UI theme.
  Fix: Wrap your application or component tree with both `<MuiThemeProvider>` and `<EmotionThemeProvider>`, ensuring the same theme object is passed to both. For Material UI v5+, the Emotion `ThemeProvider` might pick up the Mui theme automatically but explicit declaration ensures compatibility.
• gotcha While `tss-react` is heavily inspired by JSS, it uses Emotion under the hood. Developers familiar with JSS might expect certain behaviors or plugins not directly available or implemented differently in Emotion.
  Fix: Refer to the `tss-react` documentation and Emotion's official documentation for specific API behaviors and capabilities. Direct porting of JSS plugins might not be possible.
• breaking React 19 compatibility was added in `v4.9.18`. Older versions of `tss-react` may not function correctly or might display warnings when used with React 19.
  Fix: Upgrade `tss-react` to `v4.9.18` or newer to ensure full compatibility with React 19. Also ensure your `@types/react` peer dependency is updated accordingly.
• breaking Material UI v7 support was added in `v4.9.16`. Using `tss-react` with Material UI v7 without this update may lead to peer dependency warnings or runtime issues.
  Fix: Upgrade `tss-react` to `v4.9.16` or newer when using Material UI v7 to resolve compatibility issues.

Install

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

Imports

• makeStyles
  wrong:

  const { makeStyles } = require('tss-react')

  correct:

  import { makeStyles } from 'tss-react'

  The primary API for defining styles in a JSS-like structure using a hook. Prefer ESM imports.
• useStyles
  wrong:

  const classes = useStyles()

  correct:

  const { classes } = useStyles()

  This is the return value of the `makeStyles` hook. It's a destructuring assignment, not a direct import from 'tss-react'.
• withStyles
  wrong:

  import { withStyles } from 'tss-react'

  correct:

  import { withStyles } from 'tss-react/mui'

  An improved HOC API for migrating from Material-UI v4's `withStyles`. Note the specific `/mui` subpath.
• useTheme
  wrong:

  import { useTheme } from 'tss-react'

  correct:

  import { useTheme } from '@emotion/react'

  While tss-react integrates with Emotion, the `useTheme` hook to access the theme is typically imported directly from `@emotion/react`.

Quickstart

This quickstart demonstrates how to define and use dynamic styles with `makeStyles` and `useStyles` hooks, passing props to generate conditional styles, and accessing theme properties. It also shows basic `cx` utility usage.

import React from 'react';
import { makeStyles } from 'tss-react';

interface MyComponentProps {
  variant?: 'primary' | 'secondary';
  isActive?: boolean;
}

const useStyles = makeStyles<MyComponentProps>()(
  (theme, { variant, isActive }) => ({
    container: {
      padding: '16px',
      backgroundColor: variant === 'primary' ? 'lightblue' : 'lightgray',
      borderRadius: '8px',
      border: isActive ? '2px solid blue' : 'none',
      '&:hover': {
        boxShadow: '0px 0px 8px rgba(0,0,0,0.2)'
      }
    },
    title: {
      color: theme.palette?.primary?.main || 'navy',
      fontSize: '24px',
      marginBottom: '8px'
    },
    description: {
      color: 'darkslategray',
      fontSize: '16px'
    }
  })
);

function MyComponent({ variant = 'primary', isActive = false }: MyComponentProps) {
  const { classes, cx, theme } = useStyles({ variant, isActive });

  return (
    <div className={cx(classes.container, { 'active-state': isActive })}>
      <h2 className={classes.title}>Hello from TSS-React!</h2>
      <p className={classes.description}>This component demonstrates dynamic styling with props and Emotion theme access.</p>
      <p>Current theme primary color: {theme.palette?.primary?.main || 'N/A'}</p>
    </div>
  );
}

// To run this, you'd typically wrap it in an Emotion `ThemeProvider`
// and a Material-UI `ThemeProvider` if using `@mui/material`.
// Example usage:
// function App() {
//   const muiTheme = createTheme({
//     palette: { primary: { main: '#1976d2' } }
//   });
//   return (
//     <MuiThemeProvider theme={muiTheme}>
//       <EmotionThemeProvider theme={muiTheme}>
//         <MyComponent variant="secondary" isActive={true} />
//       </EmotionThemeProvider>
//     </MuiThemeProvider>
//   );
// }

export default MyComponent;