Pigment CSS is a zero-runtime CSS-in-JS library that extracts the colocated styles to their own CSS files at build time.
[](https://github.com/mui/pigment-css/blob/HEAD/LICENSE)
[](https://www.npmjs.com/package/@pigment-css/react)
[](https://www.npmjs.com/package/@pigment-css/react)
[](https://app.codecov.io/gh/mui/pigment-css/tree/master)
[](https://app.codecov.io/gh/mui/pigment-css/)
[](https://x.com/PigmentCSS)
[](https://github.com/mui/pigment-css/issues/2)
[](https://isitmaintained.com/project/mui/pigment-css 'Average time to resolve an issue')
[](https://opencollective.com/mui-org)
---
# Documentation
- [Getting started](#getting-started)
- [Why this project exists?](#why-choose-pigmentcss)
- [Start with Next.js](#start-with-nextjs)
- [Start with Vite](#start-with-vite)
- [Basic usage](#basic-usage)
- [Creating styles](#creating-styles)
- [Creating components](#creating-components)
- [Styling based on props](#styling-based-on-props)
- [Styling based on runtime values](#styling-based-on-runtime-values)
- [Styled component as a CSS selector](#styled-component-as-a-css-selector)
- [Typing props](#typing-props)
- [sx prop](#sx-prop)
- [Theming](#theming)
- [Accessing theme values](#accessing-theme-values)
- [CSS variables support](#css-variables-support)
- [Color schemes](#color-schemes)
- [Switching color schemes](#switching-color-schemes)
- [TypeScript](#typescript)
- [Right-to-left support](#right-to-left-support)
- [How-to guides](#how-to-guides)
- [Coming from Emotion or styled-components](#coming-from-emotion-or-styled-components)
- [How Pigment CSS works](#how-pigmentcss-works)
## Getting started
Pigment CSS supports Next.js and Vite with support for more bundlers in the future.
You must install the corresponding plugin, as shown below.
### Why choose Pigment CSS
Thanks to recent advancements in CSS (like CSS variables and `color-mix()`), "traditional" CSS-in-JS solutions that process styles at runtime are no longer required for unlocking features like color transformations and theme variables which are necessary for maintaining a sophisticated design system.
Pigment CSS addresses the needs of the modern React developer by providing a zero-runtime CSS-in-JS styling solution as a successor to tools like Emotion and styled-components.
Compared to its predecessors, Pigment CSS offers improved DX and runtime performance (though at the cost of increased build time) while also being compatible with React Server Components.
Pigment CSS is built on top of [WyW-in-JS](https://wyw-in-js.dev/), enabling to provide the smoothest possible experience for Material UI users when migrating from Emotion in v5 to Pigment CSS in v6.
### Start with Next.js
#### Quickstart
Use the following commands to quickly create a new Next.js project with Pigment CSS set up:
```bash
curl https://codeload.github.com/mui/pigment-css/tar.gz/master | tar -xz --strip=2 pigment-css-master/examples/pigment-css-nextjs-ts
cd pigment-css-nextjs-ts
```
#### Manual installation
```bash
npm install @pigment-css/react
npm install --save-dev @pigment-css/nextjs-plugin
```
Then, in your `next.config.js` file, import the plugin and wrap the exported config object:
```js
const { withPigment } = require('@pigment-css/nextjs-plugin');
module.exports = withPigment({
// ... Your nextjs config.
});
```
Finally, import the stylesheet in the root `layout.tsx` file:
```diff
import type { Metadata } from 'next';
+import '@pigment-css/react/styles.css';
export const metadata: Metadata = {
title: 'Create Next App',
description: 'Generated by create next app',
};
export default function RootLayout(props: { children: React.ReactNode }) {
return (
{props.children}
);
}
```
### Start with Vite
#### Quickstart
Use the following commands to quickly create a new Vite project with Pigment CSS set up:
```bash
curl https://codeload.github.com/mui/pigment-css/tar.gz/master | tar -xz --strip=2 pigment-css/examples/pigment-css-vite-ts
cd pigment-css-vite-ts
```
#### Manual installation
```bash
npm install @pigment-css/react@next
npm install --save-dev @pigment-css/vite-plugin@next
```
Then, in your Vite config file, import the plugin and pass it to the `plugins` array as shown:
```js
import { pigment } from '@pigment-css/vite-plugin';
export default defineConfig({
plugins: [
pigment(),
// ... Your other plugins.
],
});
```
Finally, import the stylesheet in the root `main.tsx` file:
```diff
import * as React from 'react';
import { createRoot } from 'react-dom/client';
+import '@pigment-css/react/styles.css';
import App from './App';
const rootElement = document.getElementById('root');
const root = createRoot(rootElement);
root.render(
I am invisible
;
}
```
The call to the `css` function is replaced with a unique string that represents the CSS class name for the generated styles.
Use a callback function to get access to the [theme](#theming) values:
```js
const title = css(({ theme }) => ({
color: theme.colors.primary,
fontSize: theme.spacing.unit * 4,
fontFamily: theme.typography.fontFamily,
}));
```
### Creating components
Use the `styled` API to create a component by passing styles at the end. The usage should be familiar if you've worked with Emotion or styled-components:
```js
import { styled } from '@pigment-css/react';
const Heading = styled('div')({
fontSize: '4rem',
fontWeight: 'bold',
padding: '10px 0px',
});
function App() {
return Hello
``` #### Styled component as a CSS selector All of the components that you create are also available as CSS selectors. For example, for the `Heading` component described in the previous section, you can target that component inside another styled component like this: ```jsx const Wrapper = styled.div({ [`& ${Heading}`]: { color: 'blue', }, }); ``` This enables you to override the default `color` of the Heading component rendered inside the Wrapper: ```tsxI am invisible
;
}
```
The call to the `keyframes` function is replaced with a unique string that represents the CSS animation name. It can be used with `css` or `styled` too.
```js
import { css, styled, keyframes } from '@pigment-css/react';
const fadeIn = keyframes(...);
const Example2 = styled('div')({
animation: `${fadeIn} 0.5s`,
});
function App() {
return (
<>
```
For a React component like the example below, it must pass the `className` and `style` props to the underlying DOM element, otherwise the styles won't be applied.
```js
// /path/to/AnyComponent.js
const AnyComponent = (props) => {
return ;
};
// /path/to/App.js
({ color: theme.colors.primary })} />
```
- an array of plain style objects or callback functions. This is useful for applying conditional styles based on other variables:
```js
({ opacity: theme.state.disabledOpacity }) : { opacity: 1 },
]}
/>
```
### TypeScript
To use `sx` prop on HTML element, you need to augment the `HTMLAttributes` interface. Add the following code to a file that is included in your tsconfig.json:
```ts
type Theme = {
// your theme type
};
declare global {
namespace React {
interface HTMLAttributes {
sx?:
| React.CSSProperties
| ((theme: Theme) => React.CSSProperties)
| ReadonlyArray React.CSSProperties)>;
}
}
}
```
## Right-to-left support
To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows to generate styles for both directions:
### Next.js
```js
const { withPigment } = require('@pigment-css/nextjs-plugin');
// ...
module.exports = withPigment(nextConfig, {
theme: yourCustomTheme,
// CSS output option
css: {
// Specify your default CSS authoring direction
defaultDirection: 'ltr',
// Generate CSS for the opposite of the `defaultDirection`
// This is set to `false` by default
generateForBothDir: true,
},
});
```
### Vite
```js
import { pigment } from '@pigment-css/vite-plugin';
export default defineConfig({
plugins: [
pigment({
theme: yourTheme,
css: {
// Specify your default CSS authoring direction
defaultDirection: 'ltr',
// Generate CSS for the opposite of the `defaultDirection`
// This is set to `false` by default
generateForBothDir: true,
},
}),
// ... other plugins.
],
});
```
### Generated CSS
For example, if you've specified `defaultDirection: 'ltr'` and `dir="rtl"`, and your authored CSS looks like this:
```js
import { css } from '@pigment-css/react';
const className = css`
margin-left: 10px,
margin-right: 20px,
padding: '0 10px 20px 30px'
`;
```
Then the actual CSS output would be:
```css
.cmip3v5 {
margin-left: 10px;
margin-right: 20px;
padding: 0 10px 20px 30px;
}
[dir='rtl'] .cmip3v5 {
margin-right: 10px;
margin-left: 20px;
padding: 0 30px 20px 10px;
}
```
### Custom dir selector
The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize it by passing an optional `getDirSelector` method to the `css` property in your bundler config:
```js
css: {
getDirSelector(dir: string) {
// return a custom selector you'd like to use
return `:dir(${dir})`;
},
},
```
## How-to guides
### Coming from Emotion or styled-components
Emotion and styled-components are runtime CSS-in-JS libraries. What you write in your styles is what you get in the final bundle, which means the styles can be as dynamic as you want with bundle size and performance overhead trade-offs.
On the other hand, Pigment CSS extracts CSS at build time and replaces the JavaScript code with hashed class names and some CSS variables. This means that it has to know all of the styles to be extracted ahead of time, so there are rules and limitations that you need to be aware of when using JavaScript callbacks or variables in Pigment CSS's APIs.
Here are some common patterns and how to achieve them with Pigment CSS:
1. **Fixed set of styles**
In Emotion or styled-components, you can use props to create styles conditionally:
```js
const Flex = styled('div')((props) => ({
display: 'flex',
...(props.vertical // ❌ Pigment CSS will throw an error
? {
flexDirection: 'column',
paddingBlock: '1rem',
}
: {
paddingInline: '1rem',
}),
}));
```
But in Pigment CSS, you need to define all of the styles ahead of time using the `variants` key:
```js
const Flex = styled('div')((props) => ({
display: 'flex',
variants: [
{
props: { vertical: true },
style: {
flexDirection: 'column',
paddingBlock: '1rem',
},
},
{
props: { vertical: false },
style: {
paddingInline: '1rem',
},
},
],
}));
```
> 💡 Keep in mind that the `variants` key is for fixed values of props, for example, a component's colors, sizes, and states.
2. **Programatically generated styles**
For Emotion and styled-components, the styles are different on each render and instance because the styles are generated at runtime:
```js
function randomBetween(min: number, max: number) {
return Math.floor(Math.random() * (max - min + 1) + min);
}
function generateBubbleVars() {
return `
--x: ${randomBetween(10, 90)}%;
--y: ${randomBetween(15, 85)}%;
`;
}
function App() {
return (
{value}
{unit}
);
});
export default Stat;
```
### 3. Style slots based on props
In this example, a prop named `variant` is defined to let consumers change the appearance of the `Stat` component.
Pass down the `variant` prop to `` to style the `root` slot, as shown below:
```diff
const Stat = React.forwardRef(function Stat(props, ref) {
+ const { value, unit, variant, ...other } = props;
return (
-
- {value}
- {unit}
-
+
+ {value}
+ {unit}
+
);
});
```
Then you can use Pigment CSS variants API to style it when `variant` prop has a value of `outlined`:
```diff
const StatRoot = styled('div', {
name: 'PigmentStat',
slot: 'root',
})({
display: 'flex',
flexDirection: 'column',
gap: '1rem',
padding: '0.75rem 1rem',
backgroundColor: '#f9f9f9',
borderRadius: '8px',
boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
letterSpacing: '-0.025em',
fontWeight: 600,
+ variants: [
+ {
+ props: { variant: 'outlined' },
+ style: {
+ border: `2px solid #e9e9e9`,
+ },
+ },
+ ],
});
```
This completes the reusable statistics component.
If this were a real UI library, the component would be ready to upload to a package registry so others could use it.
### Consumer usage
Developers using your component must first install your package as well as the Pigment CSS packages that correspond to the [framework](#start-with-nextjs) they're using.
```bash
npm install your-package-name @pigment-css/react
npm install -D @pigment-css/nextjs-plugin
```
Next, they must set up Pigment CSS in their project:
```js
// framework config file, for example next.config.js
const { withPigment } = require('@pigment-css/nextjs-plugin');
module.exports = withPigment(
{
// ... Your nextjs config.
},
{ transformLibraries: ['your-package-name'] },
);
```
Finally, they must import the stylesheet in the root layout file:
```js
// index.tsx
import '@pigment-css/react/styles.css';
```
Then they can use your component in their project:
```jsx
import Stat from 'your-package-name/Stat';
function App() {
return
{[...Array(10)].map((_, index) => (
))}
)
}
```
However, in Pigment CSS with the same code as above, all instances have the same styles and won't change between renders because the styles are extracted at build time.
To achieve the same result, you need to move the dynamic logic to props and pass the value to CSS variables instead:
```js
function randomBetween(min: number, max: number) {
return Math.floor(Math.random() * (max - min + 1) + min);
}
const Bubble = styled('div')({
'--x': props => props.x,
'--y': props => props.y,
});
function App() {
return (
{[...Array(10)].map((_, index) => (
)
}
```
## Building reusable components for UI libraries
The purpose of this guide is to demonstrate how to create reusable components for a UI library that can be shared across multiple projects and used to implement different design systems through custom theming.
The approach outlined here is not necessary when constructing components to be consumed and themed in a single project.
It's most relevant for developers who want to build a component library that could be published as a package to be consumed and themed by other developers.
The steps below will walk you through how to create a statistics component that could serve as part of a reusable UI library built with Pigment CSS.
This process has three parts:
1. [Create component slots](#1-create-component-slots).
2. [Compose slots to create the component](#2-create-the-component).
3. [Style slots based on props](#3-style-slots-based-on-props).
### 1. Create component slots
Slots let the consumers customize each individual element of the component by targeting its respective name in the [theme's styleOverrides](#themeable-statistics-component).
This statistics component is composed of three slots:
- `root`: the container of the component
- `value`: the number to be displayed
- `unit`: the unit or description of the value
> 💡 Though you can give these slots any names you prefer, we recommend using `root` for the outermost container element for consistency with the rest of the library.
Use the `styled` API with `name` and `slot` parameters to create the slots, as shown below:
```js
// /path/to/Stat.js
import * as React from 'react';
import { styled } from '@pigment-css/react';
const StatRoot = styled('div', {
name: 'PigmentStat', // The component name
slot: 'root', // The slot name
})({
display: 'flex',
flexDirection: 'column',
gap: '1rem',
padding: '0.75rem 1rem',
backgroundColor: '#f9f9f9',
borderRadius: '8px',
boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
letterSpacing: '-0.025em',
fontWeight: 600,
});
const StatValue = styled('div', {
name: 'PigmentStat',
slot: 'value',
})({
font: '1.2rem "Fira Sans", sans-serif',
});
const StatUnit = styled('div', {
name: 'PigmentStat',
slot: 'unit',
})({
font: '0.875rem "Fira Sans", sans-serif',
color: '#121212',
});
```
### 2. Create the component
Assemble the component using the slots created in the previous step:
```js
// /path/to/Stat.js
import * as React from 'react';
// ...slot styled-components
const Stat = React.forwardRef(function Stat(props, ref) {
const { value, unit, ...other } = props;
return (