<commit_before><img align="right" title="cssobj logo" alt="cssobj logo" align="bottom" src="https://avatars0.githubusercontent.com/u/20465580?v=3&s=132" border="30" hspace="0" vspace="20">

# CSSOBJ [![Join the chat at https://gitter.im/css-in-js/cssobj](https://badges.gitter.im/css-in-js/cssobj.svg)](https://gitter.im/css-in-js/cssobj)

Runtime CSS manager, Turn CSS into dynamic JS module, Stylesheet [CRUD][] (Create, Read, Update, Delete) in CSSOM, Solve common problems of CSS-in-JS.

 - ~4K min.gz, simple API
 - Support Any CSS Selector/Value
 - [Can Write SCSS/LESS Directly](https://github.com/cssobj/babel-plugin-transform-cssobj)
 - [CSS Rules CRUD][CRUD]
 - [Put class names into local space **No Conflict**](https://cssobj.github.io/cssobj-demo/#demo4)
 - [Use JS function as CSS value](https://github.com/cssobj/cssobj/wiki/Function-as-CSS-Value)
 - [Conditional Apply CSS](https://cssobj.github.io/cssobj-demo/test/test.html)
 - [Auto Vendor Prefixer](http://1111hui.com/github/css/cssobj-demo/#demoprefixer)
 - [Media Query hook for IE8](https://cssobj.github.io/cssobj-demo/#demomedia)
 - [Server Rendering][server]

[Usage](https://github.com/cssobj/cssobj#usage) - [Wiki](https://github.com/cssobj/cssobj/wiki) - [API](https://github.com/cssobj/cssobj/blob/master/docs/api.md) - [Demo](https://cssobj.github.io/cssobj-demo/) - [Repo](https://github.com/cssobj/cssobj) - [Babel](https://github.com/cssobj/cssobj#work-flow-with-babel-see-also-without-babel-version) - [Without Babel](https://github.com/cssobj/cssobj#work-flow-without-babel)

[![Build Status](https://travis-ci.org/cssobj/cssobj.svg?branch=master)](https://travis-ci.org/cssobj/cssobj)
[![npm](https://img.shields.io/npm/v/cssobj.svg "Version")](https://www.npmjs.com/package/cssobj)
[![Coverage Status](https://coveralls.io/repos/github/cssobj/cssobj-core/badge.svg?branch=master)](https://coveralls.io/github/cssobj/cssobj-core?branch=master)
[![dependencies Status](https://david-dm.org/cssobj/cssobj/status.svg)](https://david-dm.org/cssobj/cssobj)
[![Standard - JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)


## Install:

#### npm

``` bash
npm install cssobj  # the lib

# When use Babel
npm install babel-plugin-transform-cssobj

# When **NOT** use Babel, install the converter
npm install -g cssobj-converter
```

#### browser

``` html
<script src="https://unpkg.com/cssobj"></script>
```

## Usage

First see this [SIMPLE DEMO](http://jsbin.com/cibetuc/edit?html,js,output)

In the example, `cssobj` will create `<style>` tag in HEAD, render CSS rules inside

```javascript
import cssobj from 'cssobj'

var obj = {
  div: {
    backgroundColor: 'yellow',
    color: 'red',
    // simulate 50vh in CSS3
    height: () => window.innerHeight/2 + 'px'
  }
}
var result = cssobj(obj)

// dynamic update height when resize
window.onresize = () => result.update()
```

The rendered CSS (`height` is **dynamically** set to 50% of window height)

``` css
div { background-color: yellow; color: red; height: 600px; }
```

If you read the code, you've learned the API already:

**Only One** top level method: `cssobj( obj, [config] )`, all other things using `result.someMethods`, that's all, really.

## Stylesheet CRUD

For CRUD (Create, Read, Update, Delete), **dynamically change above CSS**, see below:

### 1. Update property values

You want to change color to `'blue'`

```javascript

// using static value:
obj.div.color = 'blue'
result.update()  // color is now 'blue'


// using function as value:
obj.div.color = function(v){
  return randomColor()
}
result.update()  // color is now random

```

### 2. Delete/Remove properties

You want to remove `backgroundColor`

It's just work as you expected:

```javascript

delete obj.div.backgroundColor
result.update()

```

### 3. Create/Add new properties

You want to add `'float'` and `'clear'`

It's just work as you expected:

```javascript
obj.div.float = 'left'
obj.div.clear = 'both'
result.update()
```

### 4. Create/Add new rules

You want to add `':after'` rule, and `div span` rule

```javascript
obj.div['&:after'] = { fontSize:'10px', content:'"---"' }
obj.div.span = { fontSize: '18px' }
result.update()
```

### 5. Update/Replace rules

You want to replace the whole rule

```javascript
obj.div.span = { color: 'green', fontSize: '20px' }
result.update()
```

**All the above can use `function` instead**

```javascript
obj.div.span = function() {
  return { color: randomColor(), fontSize: currentSize + 'px' }
}
result.update()
```

### 6. Delete/Remove rules

You want to remove `div span` rule

```javascript
delete obj.div.span
result.update()
```

### 7. Read a rule

Although `cssobj` can manage everything, you read the rule in stylesheet manually

```javascript
const rule = result.root.children.div.omRule[0]
// => CSSStyleRule
rule.color = 'red'
```

### 8. Delete/Destroy cssobj

Currently, `cssobj` don't provide `result.destroy()` or similar method, you should manually destroy things:

```javascript
// remove <style> tag
result.cssdom.parentNode.removeChild(el)
// GC result
result = null
```

Think of this: one `cssobj` instance === A `<style>` tag with rules <kbd>+</kbd> `A manager from JS`

## Work Flow with Babel, See also [Without Babel Version](https://github.com/cssobj/cssobj#work-flow-without-babel)

If use [Babel](http://babeljs.io/docs/usage/cli/), recommended the [babel-plugin-transform-cssobj](https://github.com/cssobj/babel-plugin-transform-cssobj)

```javascript
// create <style> in <head>, insert CSS rules, random namespace: _1jkhrb92_

// The babel-plugin only transform: CSSOBJ `text`
<commit_msg>docs: add localize class name section<commit_after><img align="right" title="cssobj logo" alt="cssobj logo" align="bottom" src="https://avatars0.githubusercontent.com/u/20465580?v=3&s=132" border="30" hspace="0" vspace="20">

# CSSOBJ [![Join the chat at https://gitter.im/css-in-js/cssobj](https://badges.gitter.im/css-in-js/cssobj.svg)](https://gitter.im/css-in-js/cssobj)

Runtime CSS manager, Turn CSS into dynamic JS module, Stylesheet [CRUD][] (Create, Read, Update, Delete) in CSSOM, Solve common problems of CSS-in-JS.

 - ~4K min.gz, simple API
 - Support Any CSS Selector/Value
 - [Can Write SCSS/LESS Directly](https://github.com/cssobj/babel-plugin-transform-cssobj)
 - [CSS Rules CRUD][CRUD]
 - [Put class names into local space **No Conflict**](https://cssobj.github.io/cssobj-demo/#demo4)
 - [Use JS function as CSS value](https://github.com/cssobj/cssobj/wiki/Function-as-CSS-Value)
 - [Conditional Apply CSS](https://cssobj.github.io/cssobj-demo/test/test.html)
 - [Auto Vendor Prefixer](http://1111hui.com/github/css/cssobj-demo/#demoprefixer)
 - [Media Query hook for IE8](https://cssobj.github.io/cssobj-demo/#demomedia)
 - [Server Rendering][server]

[Usage](https://github.com/cssobj/cssobj#usage) - [Wiki](https://github.com/cssobj/cssobj/wiki) - [API](https://github.com/cssobj/cssobj/blob/master/docs/api.md) - [Demo](https://cssobj.github.io/cssobj-demo/) - [Repo](https://github.com/cssobj/cssobj) - [Babel](https://github.com/cssobj/cssobj#work-flow-with-babel-see-also-without-babel-version) - [Without Babel](https://github.com/cssobj/cssobj#work-flow-without-babel)

[![Build Status](https://travis-ci.org/cssobj/cssobj.svg?branch=master)](https://travis-ci.org/cssobj/cssobj)
[![npm](https://img.shields.io/npm/v/cssobj.svg "Version")](https://www.npmjs.com/package/cssobj)
[![Coverage Status](https://coveralls.io/repos/github/cssobj/cssobj-core/badge.svg?branch=master)](https://coveralls.io/github/cssobj/cssobj-core?branch=master)
[![dependencies Status](https://david-dm.org/cssobj/cssobj/status.svg)](https://david-dm.org/cssobj/cssobj)
[![Standard - JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)


## Install:

#### npm

``` bash
npm install cssobj  # the lib

# When use Babel
npm install babel-plugin-transform-cssobj

# When **NOT** use Babel, install the converter
npm install -g cssobj-converter
```

#### browser

``` html
<script src="https://unpkg.com/cssobj"></script>
```

## Usage

First see this [SIMPLE DEMO](http://jsbin.com/cibetuc/edit?html,js,output)

In the example, `cssobj` will create `<style>` tag in HEAD, render CSS rules inside

```javascript
import cssobj from 'cssobj'

const obj = {
  div: {
    backgroundColor: 'yellow',
    color: 'red',
    // simulate 50vh in CSS3
    height: () => window.innerHeight/2 + 'px'
  }
}
const result = cssobj(obj)

// dynamic update height when resize
window.onresize = () => result.update()
```

The rendered CSS (`height` is **dynamically** set to 50% of window height)

``` css
div { background-color: yellow; color: red; height: 600px; }
```

If you read the code, you've learned the API already:

**Only One** top level method: `cssobj( obj, [config] )`, all other things using `result.someMethods`, that's all, really.

## Stylesheet CRUD

The power of cssobj is CSS CRUD (Create, Read, Update, Delete), **dynamically change above CSS**, see below:

### 1. Update property values

You want to change color to `'blue'`

```javascript

// using static value:
obj.div.color = 'blue'
result.update()  // color is now 'blue'


// using function as value:
obj.div.color = function(v){
  return randomColor()
}
result.update()  // color is now random

```

### 2. Delete/Remove properties

You want to remove `backgroundColor`

It's just work as you expected:

```javascript

delete obj.div.backgroundColor
result.update()

```

### 3. Create/Add new properties

You want to add `'float'` and `'clear'`

It's just work as you expected:

```javascript
obj.div.float = 'left'
obj.div.clear = 'both'
result.update()
```

### 4. Create/Add new rules

You want to add `':after'` rule, and `div span` rule

```javascript
obj.div['&:after'] = { fontSize:'10px', content:'"---"' }
obj.div.span = { fontSize: '18px' }
result.update()
```

### 5. Update/Replace rules

You want to replace the whole rule

```javascript
obj.div.span = { color: 'green', fontSize: '20px' }
result.update()
```

**All the above can use `function` instead**

```javascript
obj.div.span = function() {
  return { color: randomColor(), fontSize: currentSize + 'px' }
}
result.update()
```

### 6. Delete/Remove rules

You want to remove `div span` rule

```javascript
delete obj.div.span
result.update()
```

### 7. Read a rule

Although `cssobj` can manage everything, you read the rule in stylesheet manually

```javascript
const rule = result.root.children.div.omRule[0]
// => CSSStyleRule
rule.color = 'red'
```

### 8. Delete/Destroy cssobj

Currently, `cssobj` don't provide `result.destroy()` or similar method, you should manually destroy things:

```javascript
// remove <style> tag
result.cssdom.parentNode.removeChild(el)
// GC result
result = null
```

Think of this: one `cssobj` instance === A `<style>` tag with rules <kbd>+</kbd> `A manager from JS`

## Localize class names

Passing `local: true` as option, cssobj will add a random `name space` into all **class names**, this is called `localize`:

``` javascript
const result = cssobj(
  {
    '.nav': {color: 'red'}
  },
  { local: true }
)
```

Rendered CSS:

``` css
.nav_1lwyllh4_ {color: red;}
```

You can get this `name space` using `result.space`, or using below methods:

``` javascript
// As HTML class attribute
result.mapClass('nav active')  // [string] 'nav_1lwyllh4_ active_1lwyllh4_'

// As CSS selector
result.mapSel('.nav li.item')  // [string] '.nav_1lwyllh4_ li.item_1lwyllh4_'
```

## Work Flow with Babel, See also [Without Babel Version](https://github.com/cssobj/cssobj#work-flow-without-babel)

If use [Babel](http://babeljs.io/docs/usage/cli/), recommended the [babel-plugin-transform-cssobj](https://github.com/cssobj/babel-plugin-transform-cssobj)

```javascript
// create <style> in <head>, insert CSS rules, random namespace: _1jkhrb92_

// The babel-plugin only transform: CSSOBJ `text`

{'fraction_non_alphanumeric': 0.17257190496040017, 'fraction_numerical': 0.0098374322634431, 'mean_word_length': 4.4453018610985024, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 29, 'https://': 56, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '34596', 'n_tokens_mistral': 4286, 'n_tokens_neox': 4174, 'n_words': 1040}