stylemap
v0.4.3
Published
CSS in JS/TS
Downloads
17
Readme
StyleMap
CSS-in-JS with a focus on ease of use, ease of debugging and type-safety.
Getting Started
Install with yarn or NPM:
yarn add stylemap
npm install --save stylemap
Style some elements!
import { styles, updateStylesheet, classes } from 'stylemap'
let hotPinkText = style('hotPink', { color: '#FF69B4' })
updateStylesheet()
let HotPink = ({children}) => <div className={classes(hotPinkText)}>{children}</div>
(this example uses React, but you can use whatever you like)
Note the use of updateStylesheet()
- registered styles must to added to the StyleMap stylesheet before they take effect. This is a deliberate design to avoid creating styles on-the-fly, which is slow and unpredictable.
Creating Styles
Styles are created by passing a name and Styles
object into the style
function:
let myStyle = style('style-name', { color: 'red' })
Note that the name will have a number appended to it to create the CSS class name (see below for more detail).
StyleMap comes with TypeScript types, so you'll get autocomplete and type information when building the Styles
object passed into style
.
Property names are camel case (e.g. paddingTop
), and will be converted to kebab case in CSS (e.g. padding-top
). Vendor-specific properties are pascal case (e.g. MozTabSize
) and are converted to kebab case with a leading dash (e.g. -moz-tab-size
).
Property Types
All CSS properties accept a string, but some properties also accept a number, which will automatically be converted to a default unit (usually px
, see below for more detail).
Pseudo Class/Element Selectors
Basic pseudo class and element selectors can be included in a Styles
object and will be appended to the parent selector to create a new CSS rule.
Code:
style('textbox', { ':focus': { background: 'lightgreen' } })
CSS:
.textbox-0:focus { background: lightgreen; }
Nested Selectors
More complex selectors can be created using the nesting property, $
. By default, nested selectors will be appended to the parent selector with a space in-between:
Code:
style('parent', { $: {
'input': { background: 'white' },
'> label': { color: 'black' }
} })
CSS:
.parent-0 input { background: white; }
.parent-0 > label { color: black; }
Selectors with &
in them will instead have their &
s replaced with the parent selector.
Code:
style('parent', { $: {
'input&': { color: 'blue' },
'&:disabled': { color: 'grey' }
} })
CSS:
input.parent-0 { color: blue; }
.parent-0:disabled { color: grey; }
Both @media
and @supports
can be nested inside a style as selectors, and will wrap the provided styling in a conditional group.
Code:
style('myThing', { $: { '@media screen': { fontSize: 'large' } } })
CSS:
@media screen { .myThing-0 { font-size: large; } }
Multiple Values
Some properties allow multiple values as an array, which will be separated appropriately. E.g.
style('ugly-box', {
padding: [4, 8, 4, 16],
background: ['linear-gradient(blue, red)', 'purple']
})
CSS:
.ugly-box-0 {
padding: 4px 8px 4px 16px
background: linear-gradient(blue, red), purple
}
CSS Functions
Some properties allow specifying the value as an object with CSS functions for the property names. E.g.
style('squeeze', { transform: { scale: 0.8, rotate: 30 } })
CSS:
.squeeze-0 { transform: scale(0.8) rotate(30deg); }
Using Styles
Class Names
To get the class name of a style, use the classes
function.
let myStyle = style('styleName', { color: 'red' })
let className = classes(myStyle); // Returns e.g. 'styleName-0'
The classes
function will also take in a nested array of styles, false
or undefined
, to produce a space-separated list of class names.
let style1 = style('red', { color: 'red' })
let style2 = style('blue', { color: 'blue' })
let undefinedStyle = undefined
let condition = false
classes([style1, [style2, undefinedStyle]]); // Returns e.g. 'red-0 blue-1'
classes([style1, condition && style2]); // Returns e.g. 'red-0`
If any of the styles passed in to classes
have not yet been rendered to the stylesheet, it will throw an error to prevent you from using styles that won't show up.
Inline Element Styles
StyleMap styles can be converted to more standard CSS style objects with the elementStyle
function.
These objects can be passed directly to a React style prop, or toString
'd for use as an element's style attribute.
// Returns { width: '100px', padding: '2px 4px' }
let inlineStyle = elementStyle({ width: 100, padding: [2, 4] })
// toString returns 'width: 100px; padding: 2px 4px;'
element.style = inlineStyle.toString()
Note that nested selectors/styles, and inline animation keyframes are not supported by elementStyle
.
Style References
To reference one style from another style, you can use template strings:
let style1 = style('inner', { border: '1px solid red' })
let style2 = style('outer', {
$: {
[`.${style1}`]: { borderColor: 'green' }
}
})
CSS:
.inner-0 { border: 1px solid red; }
.outer-1 .inner-0 { border-color: green; }
Note the .
before ${style1}
, as a style's toString()
only returns the class name.
Mixins
The style
function returns an object, which makes it easy to mix-in with other styles:
let red = style('red', { color: 'red' })
let error = style('error', {
fontWeight: 'bold',
...red
})
Animations
Animations can be defined inside another style using the animation
function:
style('popup', {
animation: animation({
from: {
opacity: 0,
transform: { translateY: '100%' }
},
to: {
opacity: 1,
transform: 'none'
}
}, 100, 'ease-out')
})
CSS:
.popup-0 { animation: popup-0-animation-0 100ms ease-out 0ms 1 normal none running; }
@keyframes popup-0-animation-0 {
from { opacity: 0; transform: translateY(100%); }
to { opacity: 1; transform: none; }
}
Note that unspecified animation properties are filled in with their defaults.
Animations can also be defined outside a style, to be re-used:
let reusableAnimation = animation('reuse-me', { 50: { transform: { scale: 2 } } }, '1s')
style('animated', {
animation: reusableAnimation,
animationIterationCount: 'infinite'
})
CSS:
.animated-0 {
animation: reuse-me-0 1s ease 0ms 1 normal none running
animation-iteration-count: infinite
}
@keyframes reuse-me-0 {
50% { transform: scale(2); }
}
Custom CSS Rules
Not all styling will be tied to CSS classes. Custom CSS rules can be registered with the cssRules
function.
Code:
cssRules({
'body': { background: 'white' },
'input:focus': { outlineColor: 'blue' }
})
CSS:
body { background: white; }
input:focus { outline-color: blue; }
Custom Fonts
Custom font faces can be registered with the fontFace
function:
let myFont = fontFace({
fontFamily: 'myFont',
fontWeight: 'bold',
src: [
{ url: '/myFont.woff', format: 'woff' },
{ local: 'Arial' }
]
})
CSS:
@font-face {
font-family: myFont
font-weight: bold
src: url(/myfont.woff) format(woff), local(Arial)
}
To use the font in a style, reference the font face's fontFamily
property:
style('special-text': { fontFamily: myFont.fontFamily })
CSS Variables
Since styles are declared statically, CSS variables are indispensable for dynamic styling. StyleMap variables provide type-safety and default units by specifying the CSS property they will be used for.
First declare the variable:
let dynamicColor = variable('color', 'variable-name'); // variable name is optional
then use the variable in a style:
let dynamicStyle = style('dynamic', { color: dynamicColor })
and set the variable in either a CSS rule, or an element's style
attribute:
cssRules({ '::global': { ...dynamicColor.set('red') } })
// or
<div style={{ ...dynamicColor.set('blue') }} />
(once again, this example uses React, but you can use whatever you like)
Generated Names
All generated class, keyframe, and variable names have a hyphenated index appended to their names. This provides the following benefits:
- Avoids conflicts with CSS from outside StyleMap.
- Ensures that names are unique, even if the same name is used more than once.
- Indicates the order that styles were registered, which helps when debugging overridden properties.
Overriding Defaults
StyleMap exposes a propertyDefaults
object, which is a map of property name to adjustment function. These adjustment functions are applied to property values to convert them to CSS strings, and can be used to provide default values, default units, or potentially other conversions. If a property isn't specified in popertyDefaults
, the default behavior is to convert numbers to px
.
StyleMap also exposes a functionDefaults
object, which is a map of function name to adjustment function. These adjustment functions work similarly to property adjustment functions, but are applied to function arguments, when used in function objects.
If you want to override any default values or units, you can used the provided defaultValue
, defaultUnit
, and defaultUnitAndValue
functions.