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

Composable and reusable style sheets.


JSS is a very thin layer which compiles JSON structures to CSS.

Take a look at "The important parts" and slides.

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

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

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

Smaller footprint because of code reuse and no vendor specific declarations

Examples

Working examples directory.

Example with extend, nesting, auto px

{
  carouselCaption: {
    extend: something,
    position: 'absolute',
    zIndex: 10,
    '&:hover': {
      background: 'red'
    }
  },
  hr: {
    height: 1,
    border: 0,
    borderTop: '1px solid #eee'
  }
}

Example with @media

{
  button: {
    width: 100
  },
  '@media (min-width: 1024px)': {
    button: {
      width: 200
    }
  }
}

Plugins

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

Some of those plugins:

• Nested rules is implemented through jss-nested plugin. Also you can do pseudo selectors like :hover via nested rules.
• Use extend property to inherit from some plain rule object, via jss-extend
• Vendor prefixes are automatically added through jss-vendor-prefixer plugin.
• You can use camel cased css property names through jss-camel-case plugin.
• Add 'px' automatically to non numeric values using jss-px

Order does matter! Here is the right one:

• jss-extend
• jss-nested
• jss-camel-case
• jss-px
• jss-vendor-prefixer
• jss-props-sort

Authoring plugins is easy.

Register plugin.

jss.use(fn)

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

jss.use(function(rule) {
    // Your modifier.
})

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, but 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 an own instance of JSS

Use an own instance if the component you build should be reusable within a different project with a probably different JSS setup.

jss.create()

var jss = require('jss').create()
jss.use(somePlugin)
jss.createStyleSheet(...)

Create style sheet with namespaces enabled.

Create a style sheet with namespaced rules.

jss.createStyleSheet([rules], [options])

Options:

• media style element attribute
• title style element attribute
• type style element attribute
• named true by default - keys are names, selectors will be generated, if false - keys are global selectors.
• link link jss Rule instances with DOM CSSRule instances so that styles, can be modified dynamically, false by default because it has some performance cost.

var sheet = jss.createStyleSheet({
    // Namespaced style sheet with generated selectors.
    myButton: {
        width: '100px',
        height: '100px'
    }
}, {media: 'print'}).attach()

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

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

Create regular style sheet with global selectors.

var sheet = jss.createStyleSheet({
    '.something': {
        width: '100px',
        height: '100px'
    }
}, {named: false}).attach()

<style>
    .something {
        width: 100px;
        height: 100px;
    }
</style>

Attach style sheet

sheet.attach()

Insert style sheet into the render tree. You need to call it in order to make your style sheet visible for the layout.

Detach style sheet

sheet.detach()

Detaching unsused style sheets will speedup every DOM node insertion and manipulation as the browser will have to do less lookups for css rules potentially to be applied to the element.

Add a rule

sheet.addRule([selector], rule)

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

Add a rule dynamically with a generated class name.

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

Add a rule with global class name.

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

Get a rule.

sheet.getRule(name)

Access a rule within sheet by selector or name.

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

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

Add multiple rules.

sheet.addRules(rules)

In case you want to add rules to the sheet separately or even at runtime.

sheet.addRules({
    myButton: {
        float: 'left',
    },
    something: {
        display: 'none'
    }
})

Create a rule without a style sheet.

jss.createRule([selector], rule)

In order to apply styles directly to the element but still be able to use jss plugins.

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

rule.applyTo(element)

Apply a rule to an element inline.

rule.applyTo(element)

This is equivalent to element.style.background = 'blue' except of that you could use a rule from sheet which is already defined and can apply plugins to it. Example.

jss.createRule({
    background: 'blue'
}).applyTo(element)

Set or get a rule property dynamically.

rule.prop(name, [value])

When option link is true, after stylesheet is attached, linker saves references to CSSRule instances so that you are able to set rules properties at any time. Example.

var sheet = jss.createStyleSheet({
    a: {
        color: 'red'
    }
}, {link: true})

// Get the color.
sheet.getRule('a').prop('color') // red

// Set the color.
sheet.getRule('a').prop('color', 'green')

Get JSON.

rule.toJSON()

Returns JSON representation of the rule. Nested rules, at-rules and array values are not supported.

Convert to CSS

sheet.toString()

If you want to get a pure CSS string from jss e.g. for preprocessing jss on the server.

var jss = require('jss')

var sheet = jss.createStyleSheet({
    myButton: {
        float: 'left',
    }
})

console.log(sheet.toString())

.jss-0 {
  float: left;
}

Install

npm install jss
#or
bower install jsstyles

A command line interface for JSS is also available:

npm install jss-cli -g

For more information see CLI.

Benchmarks

1. How fast would bootstrap css lib render? 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.

   On my machine overhead is about 10-15ms.

2. Rendering jss vs. css (same styles) jsperf bench.

Run tests

Locally

npm i
open test/local.html

From github

Tests

License

MIT