class-name v0.1.3
class-name
A simple utility function for generating a string for use as a DOM element's
className
.
The library is intended for use with React but is simple enough to be useful in any situation where you just want to build a className string.
To install: npm install class-name --save
.
API
class-name
exports two functions:
className(...classNames:ClassNameValue):className
(default export) creates a className object populated with the ClassNameValues.PropType(props:object, propName:string):void
- A React propType validator for valid ClassNameValues.
To use, simply import the library in to your project, for example with ES6 modules:
import className, { PropType } from 'class-name'
className(...className:ClassNameValue):className
This function accepts any number of valid ClassNameValues as arguments (read below to see what we consider a valid ClassNameValue).
add(...className:ClassNameValue):className
- attempts to update the current list of class names to include the provided ClassNameValues.Because className objects are immutable, if the class names list is changed, a new
className
will be returned and the original object will remain untouched. If no changes are made, the existingclassName
will be returned.has(className:string)
- returnstrue
if the string is in the list of class names,false
if not.toString():string
- returns a string of the joined class names for use with a DOM element.toClassList():array
- returns an array of the unique class names.Warning: This function currently returns the data structure used by the function internals for efficient className composition — do not mutate this value directly unless you're looking for weird behaviour ;)
PropType(props:Object, propName:String):void
For use with React as a PropType validator. This function will make sure the
prop value is considered a valid ClassNameValue. If the prop is valid, the
function will be void (i.e. return undefined
), if not, it will throw an
Error
. See the React PropType section for how to use this.
ClassNameValue
In the scope of the library, a valid ClassNameValue is considered any of the following:
A plain string or number (will be casted to a string).
className("hello") // "hello" className(1) // "1"
An object with a
toClassList
method (which should return an array) - e.g. aclassName
instance.className('button', className('big')) // "button big"
A plain object mapping class name prefixes to a valid class name value.
className({ hello: 'world' }) // "hello-world"
A plain object mapping class name prefixes to a truthy value — if the value is truthy, the key will be included in the class name list. If not, it will be ignored.
className({ hello: true, world: false }) // "hello"
An array of valid ClassNameValues.
className(["hello", { "world": true }]) // "hello world"
Test coverage
None at the moment, sorry! :-(
Using an object as a ClassNameValue
When you pass an object as a ClassNameValue, the object's keys will be used as a prefix to the values (the object values will just be treated as ClassNameValues).
Example outputs
className('a').toString() // "a"
className('a', 'b').toString(); // "a b"
className(['a', 'b']).toString(); // "a b"
className('a', ['b', 'c']).toString(); // "a b c"
className('a', { b: true }).toString(); // "a b"
className('a', { b: 'c' }).toString(); // "a b-c"
className('a', { b: { c: true } }).toString() // "a b-c"
className('a', { b: { c: ['d', 'e', 'f' ] } }).toString() // "a b-c-d b-c-e b-c-f"
const blueButton = className('button', 'blue');
const bigBlueButton = className(blueButton, 'big');
bigBlueButton.toString(); // "button blue big"
React PropType
When using React, you're most likely going to want to accept a className as a
component prop at some point. The library provides a simple PropType
function
which you can use to ensure the prop you receive can be handled via class-name
.
Example:
import React, { Component } from 'react';
import { className as ClassName, PropType as classNamePropType } from 'class-name';
class ButtonComponent extends Component {
static propTypes = {
className: classNamePropType
};
render() {
const className = ClassName('button', this.props.className);
return (
<button className={className}>
{this.props.children}
</button>
);
}
}
class FooComponent extends Component {
render() {
return (
<ButtonComponent className="foo-button">
Click me!
</ButtonComponent>
);
}
}