Functional style utilities for authoring JavaScript style objects
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test
.babelrc
.gitignore
.npmignore
.travis.yml
LICENSE.md
README.md
compositor.json
package.json

README.md

_understyle

Functional style utilities for authoring JavaScript style objects

Build Status js-standard-style

npm i understyle
// Example
import _style from 'understyle'

const style = _style({
  m: 2,
  flex: true
})
// { margin: 16, display: 'flex' }

Usage in React, etc.

Understyle is intended for use in functional component-based UI systems, like React. It can be used in any framework and for either inline styles or with any CSS-in-JS library.

// Example component
import React from 'react'
import _style from 'understyle'

const MyComponent = ({ children, ...props }) => {
  const style = {
    ..._style(props),
    color: 'tomato'
  }

  return <div style={style}>{children}</div>
}

export default MyComponent
// Example component instance
return (
  <div>
    <MyComponent p={2} mb={4}>
      Hello
    </MyComponent>
  </div>
)

Props

The following keys can be passed in to understyle.

Display

_style({ display: 'block' })

Width

The width prop accepts number values. Any number larger than 1 is returned as a number, to be handled with React inline styles or other CSS-in-JS solutions. Any number between 0 and 1 will become a percentage width.

_style({ width: 1 / 2 }) // { width: '50%' }
_style({ width: 1 })     // { width: '100%' }
_style({ width: 64 })    // { width: 64 }

Margin

Margin props are set based on a spacing scale for numbers 1–4. Any number above 4 will return the raw number value.

_style({
  margin: 0,        // margin: 0
  marginBottom: 3,  // marginBottom: 32
  marginX: 12       // marginLeft: 12, marginRight: 12
})

Shorthand props are also available.

_style({
  m: 0,   // margin: 0
  mb: 3, // marginBottom: 32
  mx: 12 // marginLeft: 12, marginRight: 12,
})

Padding

Padding also supports longform and shorthand keys.

_style({
  p: 0,   // padding: 0
  paddingLeft: 2, // paddingLeft: 16
  py: 48  // paddingTop: 48, paddingBottom: 48
})

Typography

_style({
  fontSize: 16,     // fontSize: 16
  align: 'center',  // textAlign: 'center'
  bold: true,       // fontWeight: 'bold'
  caps: true,       // textTransform: 'uppercase', letterSpacing: '.1em'
})

Font size also accepts numbers representing steps on the configured type scale, for any number below 7

_style({ fontSize: 1 })
// fontSize: 48

Flexbox

_style({
  flexWrap: 'wrap',     // flexWrap: 'wrap'
  alignItems: 'center', // alignItems: 'center'
  justifyContent: 'space-between', // justifyContent: 'space-between'
  flexDirection: 'column', // flexDirection: 'column'
  flexAuto: true,       // flex: '1 1 auto'
  flexNone: true,       // flex: 'none'
})

Color

Color props accept strings as either keys from the configured color object or raw color values.

_style({
  color: 'blue', // color: '#07c'
  backgroundColor: 'tomato', // color: 'tomato'
  borderColor: '#eee', // color: '#eee'
})

Border

_style({ border: true })
// border: '1px solid'

_style({ border: false })
// border: 0

_style({ border: 3 })
// border: '3px solid'

_style({ borderTop: true })
// borderTop: '1px solid'

_style({ borderRight: true })
// borderRight: '1px solid'

_style({ borderBottom: true })
// borderBottom: '1px solid'

_style({ borderLeft: true })
// borderLeft: '1px solid'

Border Radius

_style({ rounded: true })
// borderRadius: 2

_style({ rounded: false })
// borderRadius: 0

_style({ rounded: 'top' })
// borderRadius: '2px 2px 0 0'

_style({ rounded: 'right' })
// borderRadius: '0 2px 2px 0'

_style({ rounded: 'bottom' })
// borderRadius: '0 0 2px 2px'

_style({ rounded: 'left' })
// borderRadius: '2px 0 0 2px'

Responsive Styles

All props accept arrays to set styles for multiple breakpoints, where the first value is no breakpoint, then the following values are from the small breakpoint up, for a mobile-first styling approach.

_style({
  width: [
    1,
    1 / 2,
    1 / 3,
    1 / 4,
  ]
})
// {
//   width: '100%',
//   '@media screen and (min-width:40em)': {
//     width: '50%'
//   },
//   '@media screen and (min-width:52em)': {
//     width: '33.333333%'
//   },
//   '@media screen and (min-width:64em)': {
//     width: '25%'
//   }
// }

This helps create a succinct syntax for use in React components.

// Example
<Box width={[ 1, 1/2, 1/3, 1/4 ]} />

Arrays work for any understyle property, and null values can be passed to the array to skip breakpoints.

_style({
  margin: [ 0, null, 16, 32 ],
  padding: [ null, null, 16, 32 ],
  border: [ null, null, true ]
})

Shorthand Props

Understyle provides shorthand props for setting common styles. Each shorthand prop accepts a boolean value.

_style({
  mb4: true
})

These are provided as a convenience for use in React.

// Example
<Button mb4 />

The following boolean keys can be passed to understyle.

  • block - display block
  • inlineBlock - display inline-block
  • inline
  • table
  • tableRow
  • tableCell
  • flex
  • inlineFlex
  • m0 - m4 - margin
  • mt0 - mt4 - margin-top
  • mr0 - mr4 - margin-right
  • mb0 - mb4 - margin-bottom
  • ml0 - ml4 - margin-left
  • p0 - p4 - padding
  • pt0 - pt4 - padding-top
  • pr0 - pr4 - padding-right
  • pb0 - pb4 - padding-bottom
  • pl0 - pl4 - padding-left
  • left - text align left
  • center - text align center
  • right - text align right
  • justify - text align justify
  • bg - background color
  • <COLOR> - foreground color - e.g. red
  • bg<COLOR> - background color - e.g. bgRed
  • border<COLOR> - border color - e.g. borderRed

MIT License