react-jss

What is react-jss?

react-jss is a library that allows you to use JSS (JavaScript Style Sheets) with React. It provides a way to style React components using JavaScript objects, enabling dynamic styling and theming capabilities.

What are react-jss's main functionalities?

Basic Styling

This feature allows you to define styles using JavaScript objects and apply them to React components. The `createUseStyles` function is used to create a hook that generates the necessary CSS classes.

const useStyles = createUseStyles({
  button: {
    background: 'blue',
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    cursor: 'pointer'
  }
});

function MyButton() {
  const classes = useStyles();
  return <button className={classes.button}>Click Me</button>;
}

Theming

Theming allows you to define a theme object and use it to style your components. This makes it easy to apply consistent styling across your application and switch themes dynamically.

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

const useStyles = createUseStyles({
  button: {
    background: ({ theme }) => theme.primaryColor,
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    cursor: 'pointer'
  }
});

function MyButton() {
  const classes = useStyles({ theme });
  return <button className={classes.button}>Click Me</button>;
}

Dynamic Styling

Dynamic styling allows you to change styles based on component props or state. This example shows how to change the button's background color based on the `isPrimary` prop.

const useStyles = createUseStyles({
  button: {
    background: ({ isPrimary }) => (isPrimary ? 'blue' : 'gray'),
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    cursor: 'pointer'
  }
});

function MyButton({ isPrimary }) {
  const classes = useStyles({ isPrimary });
  return <button className={classes.button}>Click Me</button>;
}

Other packages similar to react-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 react-jss, styled-components uses a different syntax and approach but offers similar capabilities.

emotion

emotion is a library designed for writing CSS styles with JavaScript. It provides both a CSS-in-JS solution and a styled-components-like API. Emotion is known for its performance and flexibility, making it a strong alternative to react-jss.

aphrodite

aphrodite is a library for styling React components using JavaScript objects. It focuses on performance and ease of use, similar to react-jss. Aphrodite generates atomic CSS classes to minimize style recalculations and reflows.

README

React JSS

The benefit of using react-jss instead of using JSS directly is lazy evaluation and auto mount/unmount. It will compile your styles to CSS only when a component using them is mounted for the first time. Through ref counting, it will unmount styles when they are not in use by any of mounted component.

You need this module if you build a big application where leaving all styles in the DOM or compiling all styles at once might have performance impact or you are going to hit IE limits.

Usage

You can use it as a higher-order component to inject JSS. It can act both as a simple wrapping function and as a ES7 decorator.

React JSS wraps your React component and injects this.props.sheet, which is just a regular JSS style sheet, as a prop into your component. This is a common pattern that is used for composition in React instead of mixins, and works equally well with old-style createClass classes, as well as the ES6 classes.

Because JSS class names are namespaced by default, you will need to reach into this.props.sheet.classes to get their real names. For example, if you define a button class in your JSS stylesheet, its real name will be available as this.props.sheet.classes.button.

React JSS is compatible with live reloading using React Hot Loader.

Installation

npm install --save react-jss

Reusable components

You should use a local jss instance if you create components which will be used by external projects to avoid conflicts with their jss setup.

ES5

// jss.js

// Create a new instance of jss.
var jss = require('jss').create()
// Now all plugins are used by this instance only.
jss.use(require('jss-vendor-prefixer'))

// Pass your jss instance to react-jss
var useSheet = require('react-jss')(jss)

exports.jss = jss
exports.useSheet = useSheet

ES6

import {create} from 'jss'
import reactJss from 'react-jss'
import vendorPrefixer from 'jss-vendor-prefixer'

export let jss = create()
export let useSheet = reactJss(jss)

jss.use(vendorPrefixer())

Examples

ES5

var React = require('react')
var useSheet = require('react-jss')

// You can use jss directly too!
var jss = require('jss')
var vendorPrefixer = require('jss-vendor-prefixer')
jss.use(vendorPrefixer())

var styles = {
  button: {
    'background-color': 'yellow'
  },
  label: {
    'font-weight': 'bold'
  }
}

var Button = React.createClass({
  render: function () {
    var classes = this.props.sheet.classes

    return (
      <div className={classes.button}>
        <span className={classes.label}>
          {this.props.children}
        </span>
      </div>
    )
  }
})

module.exports = useSheet(Button, styles)

ES6

import React, { Component } from 'react'
import useSheet from 'react-jss'

// You can use jss directly too!
import jss from 'jss'
import vendorPrefixer from 'jss-vendor-prefixer'
jss.use(vendorPrefixer())

const styles = {
  button: {
    'background-color': 'yellow'
  },
  label: {
    'font-weight': 'bold'
  }
}

class Button extends Component {
  render() {
    const { classes } = this.props.sheet

    return (
      <div className={classes.button}>
        <span className={classes.label}>
          {this.props.children}
        </span>
      </div>
    )
  }
}

export default useSheet(Button, styles)

ES7 with decorators (using babel-plugin-transform-decorators-legacy)

import React, { Component } from 'react'
import useSheet from 'react-jss'

// You can use jss directly too!
import jss from 'jss'
import vendorPrefixer from 'jss-vendor-prefixer'
jss.use(vendorPrefixer())

const styles = {
  button: {
    'background-color': 'yellow'
  },
  label: {
    'font-weight': 'bold'
  }
}

@useSheet(styles)
export default class Button extends Component {
  render() {
    const { classes } = this.props.sheet

    return (
      <div className={classes.button}>
        <span className={classes.label}>
          {this.props.children}
        </span>
      </div>
    )
  }
}

Do you have a classSet helper?

We used to support a classSet helper in 0.x, but React is removing React.addons.classSet soon, and so are we. There are many alternative userland solutions, such as Jed Watson's excellent classnames library, so we suggest you use it instead.

It's easy to use with generated class names. If you're writing in ES6, you can use computed property names in the object literal:

import classSet from 'classnames'

  // ...

  render() {
    const { classes } = this.props.sheet
    return (
      <div className={classSet({
        [classes.normal]: true,
        [classes.active]: this.state.active
      })}>
        {this.props.children}
      </div>
    )
  )

If you're still writing in ES5 (you should consider Babel though!), you can just supply an array:

 var classSet = require('classnames')

  // ...

 render: function () {
    var classes = this.props.sheet.classes
    return (
      <div className={classSet(
        classes.normal,
        this.state.active && classes.active
      )}>
        {this.props.children}
      </div>
    )
  }

Either way, you can see now that there is no real need for a dedicated classSet helper in this project.

API

React JSS has two overloads. If you are using ES5 or ES6, use this overload:

// ES5 and ES6
useSheet: (ReactClass, rules[, options]) => ReactClass

It lets you pass your React component class as the first parameter.

There is also another signature designed specifically to be used with ES7 decorators. It activates if pass the styles as the first parameter instead of the component:

// ES7
useSheet: (rules, [, options]) => (ReactClass) => ReactClass

This overload returns a partial function, to which you then should pass your React component class. This is only useful because ES7 decorators expect such signature. If you use ES5 or ES6, just ignore it and use the first overload instead.

In both overloads, rules and options are the arguments to the jss.createStyleSheet call inside. If you're not sure which overload to use, go with the first one.

License

MIT