Keystyle NPM | npm.io

#keystyle

####inline (unique)key and style with React/JSX/Radium, includes the React KeyStyleMixin

#####Why?

React keys are tricky
Radium needs unique React key's in most elements
It's very hard to keep track of the key's I create and manually keep them unique
my codebase was bloated with key and style definitions in almost every (JSX)element

Basically, this:

var MyComponent= React.createClass({

	render: function(){

		return (
			<div
				key		= 'container'
				style	= { containerStyle } >

				<div
					key		= 'text'
					style	= { textStyle } >

					Hello World!

				</div>

			</div>
		);
	}

});

exports default Radium( MyComponent);

becomes this:

var MyComponent= React.createClass({

	render: function(){

		return (
			<div {...keystyle( containerStyle )} >

				<div {...keystyle( textStyle )} >
					Hello World!
				</div>

			</div>
		);
	}

});

exports default Radium( MyComponent );

It not only saves lines of code, the key identifier is made unique under the hood. Consider the following example:

	<div {...keystyle( containerStyle )} >

		<img {...keystyle( 'image', imageStyle )}
			src= '/images/image1.png' />

		<img {...keystyle( 'image', imageStyle )}
			src= '/images/image2.png' />

	</div>

Normally Radium would fail and complain about identical keys, but because keystyle renders unique keys you can specify a key with the same name over and over again, you don't have to go: 'image1', 'image2' and keep track of the count and uniqueness. In most cases it's perfectly save to simply omit the name of the key:

	<div {...keystyle( containerStyle )} >

		<img {...keystyle( imageStyle )}
			src= '/images/image1.png' />

		<img {...keystyle( imageStyle )}
			src= '/images/image2.png' />

	</div>

###Usage:

First, install with npm:

npm install --save keystyle

You can directly create a new instance of the KeyStyle object

import KeyStyle	from 'keystyle';
// reference to the KeyStyle class
const keystyle= KeyStyle.newKeyStyle( 'my-component-name' );
// creates a new KeyStyle instance and sets the base-id to 'my-component-name'
// returns an alias to KeyStyle.prototype.keystyle

or extend another object:

class myObject extends KeyStyle {

	someMethod(){
		const someElement= (
			<div {...this.keystyle( styleObject )} >
				more stuff..
			</div>
		);
	}
}

Keep in mind though that when creating a new instance or extending KeyStyle you'll have to manually clear the generated dynamic keys by calling this.resetDynamicKeys() before the React component updates! Otherwise same elements will get different keys which can cause hard to solve bugs.

Therefore my preference is to use the included mixin, which does this automatically on componentWillUpdate:

const myComponent= React.createClass({

	mixins: [ KeyStyleMixin('my-component-name') ]

	,render: function(){
		return (
			<div {...this.keystyle( containerStyle )} >
				more stuff..
			</div>
		);
	}
});

If you only need a unique key you can simply do: { this.keystyle().key }

###keystyle accepts and generates:

// totally default:
const keystyle= require( 'keystyle' ).newKeyStyle();
<div {...keystyle()} ></div>
// key= 'B1:K1'
// style= {}

// or change the base id:
const keystyle= require( 'keystyle' ).newKeyStyle( 'my-component' );
<div key= {...keystyle()} ></div>
// key= 'my-component1:K1'
// style= {}

// or make the key more specific
<div {...keystyle( 'some-id' )} ></div>
// key= 'my-component1:some-id1'
// style= {}

// add a style object
<div {...keystyle( 'some-id', {opacity: 1} )} ></div>
// key= 'my-component1:some-id1'
// style= { opacity: 1 }

// only style object
<div {...keystyle( {opacity: 1} )} ></div>
// key= 'my-component1:K1'
// style= { opacity: 1 }

// can merge multiple style objects
<div {...keystyle( 'container', {opacity: 1}, {display: 'flex'} )} ></div>
// key= 'my-component1:container1'
// style= { opacity: 1, display: flex }

// accepts style object arrays
<div {...keystyle( 'container', [{opacity: 1}, {display: 'flex'}] )} ></div>

// if you only need a unique key
<div key= { keystyle().key } ></div>
// key= 'my-component1:K1'

Although it's tempting to call keystyle without a specific key identifier, it can sometimes be better practice to add them. It not only helps writing readable code, it also creates even more specificity between elements keys.

###Static keys

Static keys are keys that won't be disposed on re-render when using the mixin. You can make a key static by prepending a key specifier with '!'.

<div {...keystyle( '!title', titleStyle )} >

Starting the key specifier with an exclamation mark prevents KeyStyleMixin from disposing the key on re-render.

###Todo

Add higher-order component implementation