JSS - JavaScript Style Sheets

10.10.0 · abandoned · verified Sun Apr 19

JSS (JavaScript Style Sheets) is a library for generating and managing CSS rules with JavaScript, offering a modular and component-based approach to styling. It allows developers to define styles directly within their JavaScript code, providing dynamic theming, server-side rendering support, and efficient style injection. The current stable version is 10.10.0, although version 10.10.1 explicitly marked the project as no longer maintained. Its key differentiators include a plugin-based architecture for extending functionality, support for various CSS features like nesting and global styles via plugins, and integration with frameworks like React through `react-jss`. It provides a powerful API to create, update, and remove stylesheets dynamically, enabling highly interactive and configurable UI styling. However, due to its abandoned status, new projects should consider actively maintained alternatives.

Common errors

```
TypeError: jss.createStyleSheet is not a function
```
cause The 'createStyleSheet' method is called on the 'jss' module object directly, instead of an instance created by the 'create' function.

fix Ensure you import the 'create' function and use it to instantiate JSS: `import { create } from 'jss'; const jss = create();`.
```
JSS: A plugin with the name 'global' is already registered.
```
cause A JSS plugin, such as `jss-plugin-global`, has been registered multiple times with the same JSS instance, or conflicting plugins are being used.

fix Ensure that `jss.use()` is called only once for each plugin instance, typically during JSS initialization. If using a preset, ensure it's applied correctly and not double-registering plugins.
```
ReferenceError: SheetsRegistry is not defined
```
cause The 'SheetsRegistry' class was used without being correctly imported, typically in a server-side rendering context.

fix Add the named import for SheetsRegistry: `import { SheetsRegistry } from 'jss';`.

Warnings

breaking The JSS project is no longer maintained, as explicitly stated in the v10.10.1 release notes. This means no further bug fixes, security updates, or new features will be provided. Relying on this package for new projects is not recommended.
Fix: For new projects, consider adopting actively maintained CSS-in-JS libraries (e.g., Emotion, Styled Components) or alternative styling approaches. For existing projects, understand the risks of unmaintained software and plan for migration.
gotcha Earlier versions of JSS had memory leaks when using nested function rules, particularly with plugins like `jss-plugin-global`, `jss-plugin-nested`, and `jss-plugin-rule-value-function`. These were addressed in v10.8.1, but a regression occurred in v10.8.2, with a final fix in v10.9.0.
Fix: Ensure you are using JSS v10.9.0 or higher to avoid known memory leaks related to function rules. If upgrading is not immediately possible, carefully profile your application for memory usage.
gotcha Users integrating `react-jss` with React 18 encountered several regressions and fixes related to the `useInsertionEffect` hook in alpha releases around v10.9.1 to v10.9.2. This could lead to incorrect style injection or hydration issues.
Fix: If using `react-jss` with React 18, ensure you are on `react-jss` version 10.9.2 or later, which contains the final fix for these regressions. Always test thoroughly when updating React or `react-jss` versions.

Install

npm install jss npm
yarn add jss yarn
pnpm add jss pnpm

Imports

create
wrong:
```
const jss = require('jss'); const create = jss.create;
```
correct:
```
import { create } from 'jss'
```
The 'create' function is the primary way to initialize a JSS instance for managing stylesheets. It's a named export.
Jss
wrong:
```
import Jss from 'jss'
```
correct:
```
import { Jss } from 'jss'
```
The 'Jss' class represents the core JSS instance type, useful for type annotations in TypeScript. It is a named export, not a default export.
SheetsRegistry
wrong:
```
const SheetsRegistry = require('jss').SheetsRegistry
```
correct:
```
import { SheetsRegistry } from 'jss'
```
SheetsRegistry is essential for server-side rendering (SSR) to collect and serialize CSS from multiple stylesheets into a single string.

Quickstart

This quickstart demonstrates how to initialize JSS, define styles, create and attach a stylesheet to the DOM, and prepare CSS for server-side rendering.

import { create } from 'jss';
import { SheetsRegistry } from 'jss';

// 1. Create a JSS instance
const jss = create();

// 2. Define your styles as a JavaScript object
const styles = {
  button: {
    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
    borderRadius: 3,
    border: 0,
    color: 'white',
    height: 48,
    padding: '0 30px',
    boxShadow: '0 3px 5px 2px rgba(255, 105, 135, .3)',
    cursor: 'pointer',
    '&:hover': {
      boxShadow: '0 5px 7px 3px rgba(255, 105, 135, .5)',
    },
  },
  container: {
    margin: '20px',
    textAlign: 'center',
    fontFamily: 'sans-serif',
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    minHeight: '100px',
  },
};

// 3. Create a stylesheet from your styles
const sheet = jss.createStyleSheet(styles, { link: true });

// 4. Attach the stylesheet to the DOM (this injects the CSS)
sheet.attach();

console.log('JSS Stylesheet attached to DOM.');
console.log('Generated CSS classes:', sheet.classes);
console.log('Full generated CSS:\n', sheet.toString());

// Example: Dynamically update a style (if rules were functions)
// For simple object styles, you might modify the object and re-attach
// const dynamicSheet = jss.createStyleSheet({ dynamicColor: (props) => ({ color: props.color }) });
// dynamicSheet.update({ color: 'blue' }).attach();

// For server-side rendering, you'd collect sheets
const sheets = new SheetsRegistry();
sheets.add(sheet);
const serverSideCss = sheets.toString();
console.log('\nCSS for Server-Side Rendering:\n', serverSideCss);

// You can detach the stylesheet if no longer needed
// sheet.detach();

view raw JSON →