tss-react

What is tss-react?

tss-react is a TypeScript-first CSS-in-JS library for React that allows you to write type-safe styles using TypeScript. It provides a simple and efficient way to manage styles in your React applications, leveraging the power of TypeScript for better type safety and developer experience.

What are tss-react's main functionalities?

Type-safe CSS-in-JS

This feature allows you to create type-safe styles using TypeScript. The `makeStyles` function generates a hook that you can use to apply styles to your components.

```typescript
import { makeStyles } from 'tss-react/makeStyles';

const useStyles = makeStyles()((theme) => ({
  root: {
    backgroundColor: theme.palette.primary.main,
    padding: theme.spacing(2),
  },
}));

function MyComponent() {
  const { classes } = useStyles();
  return <div className={classes.root}>Hello, World!</div>;
}
```

Theming support

tss-react supports theming, allowing you to create and use themes in your application. This example demonstrates how to create a theme and apply it to a component using the `ThemeProvider` from Material-UI.

```typescript
import { ThemeProvider, createTheme } from '@mui/material/styles';
import { makeStyles } from 'tss-react/makeStyles';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
  },
});

const useStyles = makeStyles()((theme) => ({
  root: {
    backgroundColor: theme.palette.primary.main,
    padding: theme.spacing(2),
  },
}));

function MyComponent() {
  const { classes } = useStyles();
  return <div className={classes.root}>Hello, World!</div>;
}

function App() {
  return (
    <ThemeProvider theme={theme}>
      <MyComponent />
    </ThemeProvider>
  );
}
```

Dynamic styles

This feature allows you to create dynamic styles based on props. The `makeStyles` function can accept a parameter that you can use to generate styles dynamically.

```typescript
import { makeStyles } from 'tss-react/makeStyles';

const useStyles = makeStyles<{ color: string }>()((theme, { color }) => ({
  root: {
    backgroundColor: color,
    padding: theme.spacing(2),
  },
}));

function MyComponent({ color }: { color: string }) {
  const { classes } = useStyles({ color });
  return <div className={classes.root}>Hello, World!</div>;
}
```

Other packages similar to tss-react

emotion

Emotion is a popular CSS-in-JS library that allows you to style applications quickly with string or object styles. It provides powerful and flexible styling capabilities, but it does not have built-in TypeScript-first support like tss-react.

styled-components

Styled-components is another widely-used CSS-in-JS library that uses tagged template literals to style components. It offers a great developer experience and theming support, but it lacks the TypeScript-first approach of tss-react.

jss

JSS is a high-performance JavaScript to CSS compiler that works well with React. It provides a powerful API for dynamic styling and theming, but it does not offer the same level of TypeScript integration as tss-react.

README

✨ Dynamic CSS-in-TS solution, based on Emotion ✨

Home - Documentation - Playground

You can think of tss-react as @emotion/jss.
It's, in essence, a type-safe equivalent of the JSS API but powered by Emotion, just like @emotion/styled is the styled-components API but powered by Emotion.

• 🚀 Seamless integration with MUI.
• 🌐 Works in Next.js App and Page Router.
• 🙅‍♂️ No custom styling syntax to learn, no shorthand, just plain CSS.
• 💫 Dynamic Style Generation: TSS enables to generate styles based on the props and internal states of components.
  This unfortunately prevents us from supporting Server Component (RSC) in Next.js.
  We remain hopeful for future support of RSC, contingent on the provision of a suitable solution by Vercel and React.
  If you need RSC support today, you can consider zero runtime solutions like Panda-CSS or Vanilla Extract, but the expression of complex styles is significantly harder in this paradigm.
• 📚 Your JSX remains readable. Unlike other styling solution that tend to clutter the JSX, TSS enables isolating the styles from the component structure.
  That been said, sometime it's just easier to inline the styles directly within your components, TSS enables this as well.
• 🛡️ Eliminate CSS priority conflicts! With TSS you can determine the precedence of multiple classes applied to a component and arbitrarily increase specificity of some rules.
• 🧩 Offers a type-safe equivalent of the JSS $ syntax.
• ⚙️ Freely customize the underlying @emotion cache.
• ✨ Improved withStyles API featured, to help you migrate away from @material-ui v4.
• 🛠️ Build on top of @emotion/react, it has very little impact on the bundle size alongside mui (~5kB minziped).
• ⬆️ 'tss-react' can be used as an advantageous replacement for @material-ui v4 makeStyles and 'react-jss'.
• 🎯 Maintained for the foreseeable future, issues are dealt with within good delays.
• 📦 Library authors: tss-react won’t be yet another entry in your peerDependencies.

demo.webm

While this module is written in TypeScript, using TypeScript in your application is optional (but recommended as it comes with outstanding benefits to both you and your codebase).

Get started 🚀

The more ⭐️ the project gets, the more time I spend improving and maintaining it. Thank you for your support 😊

Needless to mention, this library is heavily inspired by JSS, the OG CSS-in-JS solution.

Development

Running the demo apps:

git clone https://github.com/garronej/tss-react
cd tss-react
yarn
yarn build
npx tsc -w & npx tsc --module es2015 --outDir dist/esm -w
# Open another Terminal
yarn start_spa  # For testing in in a Create React App setup
yarn start_ssr # For testing in a Next.js setup
yarn start_appdir #  Next.js 13 setup in App directory mode