{"id":15869,"library":"tss-react","title":"TSS-React: Type-Safe CSS-in-JS with Emotion","description":"tss-react is a robust CSS-in-JS solution providing a type-safe API inspired by `react-jss`, but built on top of Emotion. It offers seamless integration with Material UI, supports Next.js App and Page Router environments (though not Server Components due to dynamic style generation), and enables dynamic style generation based on component props and states using plain CSS. Currently at version 4.9.20, it receives frequent patch and minor updates, indicating active development and maintenance. Key differentiators include its strong typing, a JSS-like API for developers familiar with it, the ability to isolate styles from JSX for cleaner component structures, and features like arbitrary specificity increase and a type-safe equivalent of JSS's nested selectors. It is presented as an advantageous replacement for `@material-ui v4 makeStyles` and `react-jss`, providing a maintained solution for dynamic styling with a minimal impact on bundle size.","status":"active","version":"4.9.20","language":"javascript","source_language":"en","source_url":"git://github.com/garronej/tss-react","tags":["javascript","jss","hooks","react","@material-ui","mui","css","makeStyles","withStyles","typescript"],"install":[{"cmd":"npm install tss-react","lang":"bash","label":"npm"},{"cmd":"yarn add tss-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add tss-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React dependency for components and hooks.","package":"react","optional":false},{"reason":"TypeScript type definitions for React.","package":"@types/react","optional":true},{"reason":"Underlying CSS-in-JS engine.","package":"@emotion/react","optional":false},{"reason":"Required for server-side rendering with Emotion.","package":"@emotion/server","optional":true},{"reason":"Optional integration for Material UI theming and components.","package":"@mui/material","optional":true}],"imports":[{"note":"The primary API for defining styles in a JSS-like structure using a hook. Prefer ESM imports.","wrong":"const { makeStyles } = require('tss-react')","symbol":"makeStyles","correct":"import { makeStyles } from 'tss-react'"},{"note":"This is the return value of the `makeStyles` hook. It's a destructuring assignment, not a direct import from 'tss-react'.","wrong":"const classes = useStyles()","symbol":"useStyles","correct":"const { classes } = useStyles()"},{"note":"An improved HOC API for migrating from Material-UI v4's `withStyles`. Note the specific `/mui` subpath.","wrong":"import { withStyles } from 'tss-react'","symbol":"withStyles","correct":"import { withStyles } from 'tss-react/mui'"},{"note":"While tss-react integrates with Emotion, the `useTheme` hook to access the theme is typically imported directly from `@emotion/react`.","wrong":"import { useTheme } from 'tss-react'","symbol":"useTheme","correct":"import { useTheme } from '@emotion/react'"}],"quickstart":{"code":"import React from 'react';\nimport { makeStyles } from 'tss-react';\n\ninterface MyComponentProps {\n  variant?: 'primary' | 'secondary';\n  isActive?: boolean;\n}\n\nconst useStyles = makeStyles<MyComponentProps>()(\n  (theme, { variant, isActive }) => ({\n    container: {\n      padding: '16px',\n      backgroundColor: variant === 'primary' ? 'lightblue' : 'lightgray',\n      borderRadius: '8px',\n      border: isActive ? '2px solid blue' : 'none',\n      '&:hover': {\n        boxShadow: '0px 0px 8px rgba(0,0,0,0.2)'\n      }\n    },\n    title: {\n      color: theme.palette?.primary?.main || 'navy',\n      fontSize: '24px',\n      marginBottom: '8px'\n    },\n    description: {\n      color: 'darkslategray',\n      fontSize: '16px'\n    }\n  })\n);\n\nfunction MyComponent({ variant = 'primary', isActive = false }: MyComponentProps) {\n  const { classes, cx, theme } = useStyles({ variant, isActive });\n\n  return (\n    <div className={cx(classes.container, { 'active-state': isActive })}>\n      <h2 className={classes.title}>Hello from TSS-React!</h2>\n      <p className={classes.description}>This component demonstrates dynamic styling with props and Emotion theme access.</p>\n      <p>Current theme primary color: {theme.palette?.primary?.main || 'N/A'}</p>\n    </div>\n  );\n}\n\n// To run this, you'd typically wrap it in an Emotion `ThemeProvider`\n// and a Material-UI `ThemeProvider` if using `@mui/material`.\n// Example usage:\n// function App() {\n//   const muiTheme = createTheme({\n//     palette: { primary: { main: '#1976d2' } }\n//   });\n//   return (\n//     <MuiThemeProvider theme={muiTheme}>\n//       <EmotionThemeProvider theme={muiTheme}>\n//         <MyComponent variant=\"secondary\" isActive={true} />\n//       </EmotionThemeProvider>\n//     </MuiThemeProvider>\n//   );\n// }\n\nexport default MyComponent;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<4.9.18"},{"fix":"Upgrade `tss-react` to `v4.9.16` or newer when using Material UI v7 to resolve compatibility issues.","message":"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.","severity":"breaking","affected_versions":"<4.9.16"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The theme object is not being correctly provided to `tss-react` via Emotion's `ThemeProvider`, or the theme structure is different than expected.","error":"TypeError: Cannot read properties of undefined (reading 'main') (or similar theme property access error)"},{"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.","cause":"The `makeStyles` or `useStyles` hook is being called outside of a React functional component or custom hook context.","error":"Error: Invalid hook call. Hooks can only be called inside of the body of a functional component."},{"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.","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).","error":"Cannot find module 'tss-react' or its corresponding type declarations."},{"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.","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.","error":"Type 'Classes' is not assignable to type 'string | undefined'. Property 'root' is missing in type 'Classes'."}],"ecosystem":"npm"}