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

Dynamic stylesheets for web components.

Why do we need transpilers like sass or stylus when we can use javascript to do the same and much more?

By leveraging namespaces we can solve the cascading problem better than bem and make our components truly reusable and composable.

Access css declarations and values from js without DOM round trip.

Smaller footprint because of code reuse and no vendor specific declarations

Take a look at examples directory.

Syntactic differences compared to CSS

Jss styles are just plain javascript objects. They map 1:1 to css rules, except of those modified by plugins.

Nested Rules

Put an & before a selector within a rule and it will be replaced by the parent selector and extracted to a separate rule.

{
    '.container': {
        padding: '20px',
        // Will result in .container.clear
        '&.clear': {
            clear: 'both'
        },
        // Will result in .container .button
        '& .button': {
            background: 'red'
        },
        '&.selected, &.active': {
            border: '1px solid red'
        }
    }
}

.container {
    padding: 20px;
}
.container.clear {
    clear: both;
}
.container .button {
    background: red;
}
.container.selected, .container.active {
    border: 1px solid red;
}

Inheritance

Inherit a rule(s) by using extend keyword. This makes it easy to reuse code. See example.

var rules = {}

var button1 = {
    padding: '20px',
    background: 'blue'
}

rules['.button-1'] = button1

rules['.button-2'] = {
    extend: button1, // can be an array of styles
    padding: '30px'
}

.button-1 {
    padding: 20px;
    background: blue;
}

.button-2 {
    padding: 30px;
    background: blue;
}

Vendor prefixes

Vendor prefixes are handled automatically using a smart check which results are cached. See example.

{
    '.container': {
        transform: 'translateX(100px)'
    }
}

.container {
    transform: -webkit-translateX(100px);
}

Multiple declarations with identical property names

I recommend to not to use this if you use jss on the client. Instead you should write a function, which makes a test for this feature support and generates just one final declaration.

In case you are using jss as a server side precompiler, you might want to have more than one property with identical name. This is not possible in js, so you can use an array.

{
    '.container': {
        background: [
            'red',
            '-moz-linear-gradient(left, red 0%, green 100%)',
            '-webkit-linear-gradient(left, red 0%, green 100%)',
            '-o-linear-gradient(left, red 0%, green 100%)',
            '-ms-linear-gradient(left, red 0%, green 100%)',
            'linear-gradient(to right, red 0%, green 100%)'
        ]
    }
}

.container {
    background: red;
    background: -moz-linear-gradient(left, red 0%, green 100%);
    background: -webkit-linear-gradient(left, red 0%, green 100%);
    background: -o-linear-gradient(left, red 0%, green 100%);
    background: -ms-linear-gradient(left, red 0%, green 100%);
    background: linear-gradient(to right, red 0%, green 100%);
}

API

Access the jss namespace

// Pure js
var jss = window.jss

// Commonjs
var jss = require('jss')

Create stylesheet

jss.createStylesheet([rules], [named], [attributes])

• rules is an object, where keys are selectors if named is not true
• named rules keys are not used as selectors, but as names, will cause auto generated class names and selectors. It will also make class names accessible via stylesheet.classes.
• attributes allows to set any attributes on style element.

var stylesheet = jss.createStylesheet({
    '.selector': {
        width: '100px'
    }
}, {media: 'print'}).attach()

<style media="print">
    .selector {
        width: 100px;
    }
</style>

Create namespaced stylesheet.

Create a stylesheet with namespaced rules. For this set second parameter to true.

var stylesheet = jss.createStylesheet({
    myButton: {
        width: '100px',
        height: '100px'
    }
}, true).attach()

console.log(stylesheet.classes.myButton) // .jss-0

<style>
    .jss-0 {
        width: 100px;
        height: 100px;
    }
</style>

Attach stylesheet

stylesheet.attach()

Insert stylesheet into render tree.

stylesheet.attach()

Detach stylesheet

stylesheet.detach()

Remove stylesheet from render tree to increase runtime performance.

stylesheet.detach()

Add a rule

stylesheet.addRule([selector], rule)

Returns an array of rules, because you might have a nested rule in your style.

You might want to add rules dynamically.

var rules = stylesheet.addRule('.my-button', {
    padding: '20px',
    background: 'blue'
})

Add rule with generated class name.

var rules = stylesheet.addRule({
    padding: '20px',
    background: 'blue'
})
document.body.innerHTML = '<button class="' + rules[0].className + '">Button</button>'

Get a rule

stylesheet.getRule(selector)

// Using selector
var rule = stylesheet.getRule('.my-button')

// Using name, if named rule was added.
var rule = stylesheet.getRule('myButton')

Add a rules

stylesheet.addRules(rules)

Add a list of rules.

stylesheet.addRules({
    '.my-button': {
        float: 'left',
    },
    '.something': {
        display: 'none'
    }
})

Create a rule without a stylesheet.

jss.createRule([selector], rule)

var rule = jss.createRule({
    padding: '20px',
    background: 'blue'
})

// Apply styles directly using jquery.
$('.container').css(rule.style)

Register plugin.

jss.use(fn)

Passed function will be invoked with Rule instance. Take a look at plugins extend, nested or vendorPrefixer.

jss.use(function(rule) {
    // Do something with the rule.
})

Install

npm i jss

Convert CSS to JSS

# print help
jss
# convert css
jss source.css -p > source.jss

Benchmarks

To make some realistic assumptions about performance overhead, I have converted bootstraps css to jss. In bench/bootstrap folder you will find jss and css files. You need to try more than once to have some average value.

In my tests overhead is 10-15ms.

Run tests

Locally

npm i
open test/local.html

From github

Tests

License

MIT

Changelog

10.6.0 (2021-3-14)

Improvements

• [*] Define specific polyfills for specific packages that will be required and define a policy for adding polyfills. Makes sure we will notice if a polyfill is needed in a supported browser by failing the CI. 1456
• [jss] Use globalThis to support secure version of JavaScript called SES 1449
• [jss][ts] Styles now supports ClassNames, Props/Data, and Theme as type parameters (eg. Styles<Names, Data, Theme>). 1460
• [react-jss][ts] withStyles and createUseStyles now support ClassNames, Props, and Theme as type parameters (eg. createUseStyles<Names, Props, Theme>). 1460
• [react-jss][ts] useStyles finally expects the correct argument type: a Props object with an optional Theme property (both determined from createUseStyles). 1460
• [react-jss][ts] Support global TS theme definition 1453
• [react-jss][ts] Allow partial classes prop in withStyles() 1428

Breaking Changes

• [react-jss][ts] Theme is no longer the first generic type parameter for createUseStyles. 1460
  • There are two main ways to tell TS your Theme's type without reaching over the other type parameters:

Using the function argument.

const useStyles = createUseStyles(theme: Theme => ({
  ruleName: { /* ... */ };
}))

Using the object argument with a function. (You will only need to specify the Theme type once.)

const useStyles = createUseStyles({
  ruleName: ({theme}: {theme: Theme}) => ({
    /* ... */
  })
})