jss

What is jss?

JSS (JavaScript Style Sheets) is a library for generating CSS styles with JavaScript. It allows you to define styles in a JavaScript object and apply them to your components, making it easier to manage and maintain styles in a JavaScript-centric development environment.

What are jss's main functionalities?

Creating Styles

This feature allows you to create styles using JavaScript objects. The `createStyleSheet` method generates a stylesheet from the provided styles and attaches it to the document.

const styles = {
  button: {
    color: 'blue',
    background: 'white',
    border: '1px solid blue'
  }
};

const { classes } = jss.createStyleSheet(styles).attach();

// Usage in a component
const button = document.createElement('button');
button.className = classes.button;
button.textContent = 'Click me';
document.body.appendChild(button);

Dynamic Styles

This feature allows you to create dynamic styles that can change based on props or state. The `update` method is used to update the styles with new values.

const styles = {
  button: {
    color: props => props.color,
    background: 'white',
    border: '1px solid blue'
  }
};

const sheet = jss.createStyleSheet(styles);
const { classes } = sheet.update({ color: 'red' }).attach();

// Usage in a component
const button = document.createElement('button');
button.className = classes.button;
button.textContent = 'Click me';
document.body.appendChild(button);

Theming

This feature allows you to create themes that can be applied to your styles. The styles can reference theme variables, making it easy to switch themes or update theme values.

const theme = {
  primaryColor: 'blue',
  secondaryColor: 'green'
};

const styles = theme => ({
  button: {
    color: theme.primaryColor,
    background: 'white',
    border: `1px solid ${theme.primaryColor}`
  }
});

const sheet = jss.createStyleSheet(styles(theme)).attach();
const { classes } = sheet;

// Usage in a component
const button = document.createElement('button');
button.className = classes.button;
button.textContent = 'Click me';
document.body.appendChild(button);

Other packages similar to jss

styled-components

Styled-components is a library for styling React components using tagged template literals. It allows you to write actual CSS code to style your components and supports theming and dynamic styling. Compared to JSS, styled-components is more tightly integrated with React and uses a different syntax for defining styles.

emotion

Emotion is a library designed for writing CSS styles with JavaScript. It provides both a styled API similar to styled-components and a css API for defining styles as objects. Emotion is known for its performance and flexibility, offering a similar feature set to JSS but with a different API and additional performance optimizations.

aphrodite

Aphrodite is a library for styling React components with JavaScript. It allows you to define styles as JavaScript objects and provides support for media queries and pseudo-selectors. Aphrodite is simpler and more lightweight compared to JSS, but it may lack some of the advanced features and flexibility that JSS offers.

README

JSS

JSS is a more powerful abstraction over CSS. It uses JavaScript as a language to describe styles in a declarative and maintainable way. It is a high performance JS to CSS compiler which works at runtime and server-side. This core library is low level and framework agnostic. It is about 6KB (minified and gzipped) and is extensible via plugins API.

Feel free to ask any JSS related questions on twitter by using hashtag #cssinjs and mentioning @oleg008, watch my latest talk about "Unique Value Proposition of CSSinJS" and try it on a playground.

Key features

• Framework agnostic
• Scoped selectors by default
• Function values and rules
• Observables
• SSR
• Plugins support
• Global CSS
• Expanded syntax
• Composition syntax
• Template strings syntax
• Isolation

Integrations

• React-JSS - HOC interface for React with theming, try it on playground.
• Styled-JSS - styled components interface for React, try it on playground.
• Aphrodite-JSS - aphrodite like API.

TOC

1. Live examples
2. Benefits
3. Setup
4. JSON API (JSS Syntax)
5. JavaScript API
6. Server-side rendering
7. Performance
8. Plugins API
9. Official plugins
10. All related projects
11. CLI Converter
12. Contributing

Example

Try it out on playground. You need to setup plugins before. You can use a preset for a quick setup with default plugins.

import jss from 'jss'
import preset from 'jss-preset-default'
import color from 'color'

// One time setup with default plugins and settings.
jss.setup(preset())

const styles = {
  button: {
    fontSize: 12,
    '&:hover': {
      background: 'blue'
    }
  },
  ctaButton: {
    extend: 'button',
    '&:hover': {
      background: color('blue')
        .darken(0.3)
        .hex()
    }
  },
  '@media (min-width: 1024px)': {
    button: {
      width: 200
    }
  }
}

const {classes} = jss.createStyleSheet(styles).attach()

document.body.innerHTML = `
  <button class="${classes.button}">Button</button>
  <button class="${classes.ctaButton}">CTA Button</button>
`

Result

<head>
  <style type="text/css">
    .button-123456 {
      font-size: 12px;
    }
    .button-123456:hover {
      background: blue;
    }
    .ctaButton-789012 {
      font-size: 12px;
    }
    .ctaButton-789012:hover {
      background: red;
    }
    @media (min-width: 1024px) {
      .button-123456 {
        min-width: 200px;
      }
    }
  </style>
</head>
<body>
  <button class="button-123456">Button</button>
  <button class="ctaButton-789012">CTA Button</button>
</body>

When should I use it?

• You build a JavaScript heavy application.
• You use components based architecture.
• You build a reusable UI library.
• You need a collision free CSS (external content, third-party UI components ...).
• You need code sharing between js and css.
• Minimal download size is important to you.
• Robustness and code reuse is important to you.
• Ease of maintenance is important to you.
• You just want to use any of its benefits

Roadmap

• Make it easier for newcomers to setup jss with plugins (like presets).
• Make JSON DSL even better, for e.g. jss-expand.
• Make it easy to see when changes in the core break plugins (integrate plugins test suite).
• Make community create plugins (better plugins API documentation, infrastructure).
• Introduce a way for theming with react-jss
• Help release material-ui alpha version.
• Use ISTF
• Better React Native support.
• Stylelint integration #490.
• Source maps #469
• Flow and typescript typings for the JSON DSL #375 #361
• Do more benchmarking, include plugins, always track perf regressions.
• Make SSR even better (vendor prefixer server-side, smaller critical CSS)
• Make CLI tool better: allow integration of styles written in various preprocessing languages as well as pure css #166

Browsers Support

We have automated tests running in real browsers.

License

MIT

Thanks

Thanks to BrowserStack for providing the infrastructure that allows us to run our tests in real browsers and to all awesome contributors.

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]