Skip to content

Latest commit

 

History

History
3182 lines (2228 loc) · 59.8 KB

api.md

File metadata and controls

3182 lines (2228 loc) · 59.8 KB
Raw

Table of Contents

Systems

space

import { space } from 'pss'

Spacing system for margin and padding. Created with spaceValue.

Component props:

  • m → margin
  • ml → margin-left
  • mr → margin-right
  • mt → margin-top
  • mb → margin-bottom
  • mx → margin-left, margin-right
  • my → margin-top, margin-bottom
  • p → padding
  • pl → padding-left
  • pr → padding-right
  • pt → padding-top
  • pb → padding-bottom
  • px → padding-left, padding-right
  • py → padding-top, padding-bottom

Number values:

  • Value from theme.space[mediaKey], theme.space.all or theme.space Array by index
  • Negative value for negative margins

String values:

Treated same way as in size.

  • Get value by path in theme.size or in top level theme object
  • If value in theme.sizes is an Object with media keys (like in theme.media) value is responsive
  • Other String values is passed as raw CSS value (like '10%' or '100vh').

Related: spaceValue, sizes.

Parameters

Examples

import { space } from 'pss'

const Box = styled.div`
  ${space}
`
const theme = {
  media: { sm: '(max-width: 600px)' },
  space: [ 0, 8, 16, 32, 65 ]
}

// `theme.space[1]`
<Box m={1} /> // → margin: 8px;
<Box ml={1} /> // → margin-left: 8px;

// `theme.space[2]`
<Box my={2} /> // → margin-top: 16px; margin-bottom: 16px;
<Box m={-2} /> // → margin: -16px;

// `theme.space[0]`
<Box m={0} /> // → margin: 0;

// Responsive
<Box mr={{ sm: -1 }} /> // → @media (max-width: 600px) { margin-right: -8px }
<Box mr={{ all: 2, sm: -1 }} /> // → margin-right: 16px; @media (max-width: 600px) { margin-right: -8px }

// Custom values
<Box mx='auto' /> // → margin-left: auto; margin-right: auto
<Box my='100px' /> // → margin-top: 100px; margin-bootom: 100px
const theme = {
  media: {
    sm: '(max-width: 600px)'
  },
  space: {
    all: [ 0, 10, 20, 40, 80 ],
    sm: [ 0, 8, 16, 32, 64 ],
  }
}

// `theme.space.all[1]` and `theme.space.sm[1]`
<Box m={1} /> // → margin: 10px; @media (max-width: 600px) { margin: 8px }
<Box ml={1} /> // → margin-left: 10px; @media (max-width: 600px) { margin-left: 8px }

// `theme.space.all[2]` and `theme.space.sm[2]`
<Box my={2} /> // → margin-top: 20px; margin-bottom: 20px; @media (max-width: 600px) { margin-top: 16px; margin-bottom: 16px }
<Box m={-2} /> // → margin: -20px; @media (max-width: 600px) { margin: -16px; }

// `theme.space.all[0]` and `theme.space.sm[0]`
<Box m={0} /> // → margin: 0; @media (max-width: 600px) { margin: 0 }

// Responsive
<Box mr={{ sm: -1 }} /> // → @media (max-width: 600px) { margin-right: -8px }
<Box mr={{ all: 2, sm: -1 }} /> // → margin-right: 20px; @media (max-width: 600px) { margin-right: -8px }

sizes

import { sizes } from 'pss'

Consistent sizes system for width, height. Created with sizeValue.

Component props:

  • width → width
  • maxWidth → max-width
  • minWidth → min-width
  • height → height
  • maxHeight → max-height
  • minHeight → min-height

String values:

  • Path in theme.size
  • If value in theme.sizes is an Object with media keys (like { all: 100, sm: 50 }) value is responsive
  • Other String values is passed as raw CSS value (like '10%' or '100vh').

Number values:

  • From 0-1 it is converted to percentage widths
  • Greater than 1 are converted to pixel values.

Related: sizeValue, space.

Examples use this theme:

const theme = {
  media: {
    sm: `(max-width: 600px)`
  },
  size: {
    small: '10px',
    medium: '20px',
    card: {
      all: '500px',
      sm: '300px'
    }
  }
}

Parameters

Examples

import { sizes } from 'pss'

const Box = styled.div`
  ${sizes}
`
// `theme.size.small`
<Box height='small' /> // → height: 10px

// `theme.size.card.default` and `theme.size.card.sm`
<Box width='card' /> // → width: 500px; @media (max-width: 600px) { margin-left: 300px }

// only `theme.size.card.sm`
<Box width={{ sm: 'card' }} /> // → @media (max-width: 600px) { margin-left: 300px }

// Numbers smaller that or equal to `1` is percentage value
<Box maxWidth={(1 / 2)} /> // → max-width: 50%
<Box width={1} /> // → width: 100%

// Convert numbers bigger that `1` to px
<Box minWidth={500} /> // → min-width: 500px

// Literal string values
<Box minHeight='1px' /> // → max-height: 1px

colors

import { colors } from 'pss'

Prop styles for getting current palette or color value from theme. Created with colorValue.

Result can be changed in nested components with setting other key in theme.default.palette.

Component props:

  • fg → color
  • bg → background-color
  • tm → color, background-color

String values:

  • Valid color: #f00, rgba(255, 255, 0, 0.2), hsl(0, 100%, 50%)
  • Key in theme.color or theme.palette[theme.default.palette]
    • black → theme.color.black
    • accent → theme.palette.default.accent

Default value with auto or true:

  • Different in each prop (take value from theme.palette[theme.default.palette])
    • bg → theme.palette.default.bg
    • fg → theme.palette.default.fg
    • tm → theme.palette.default.fg, theme.palette.default.bg

Related: colorValue, rule.

Examples use this theme:

const theme = {
  default: {
    palette: 'default' // this can be changed
  },
  color: {
    red: '#ff0000',
    black: '#222222',
    white: '#ffffff'
  },
  palette: {
    default: { // currently active
      bg: '#ffffff',
      fg: '#222222',
      accent: '#ff0000'
    },
    inverted: {
      bg: '#222222',
      fg: '#ffffff',
      accent: '#ff0000'
    }
  }
}

Parameters

Examples

import { colors } from 'pss'

const Box = styled.div`
  ${colors}
`
// theme.palette.default.bg
<Box bg /> // background-color: #ffffff
<Box bg='auto' /> // background-color: #ffffff

// theme.colors.black
<Box fg='black' /> // color: #222222

// theme.palette.default.accent
<Box fg='accent' /> // color: #ff0000

// theme.palette.default.bg, theme.palette.default.fg
<Box tm /> // background-color: #ffffff; color: #222222
<Box tm='auto' /> // background-color: #ffffff; color: #222222

// theme.palette.inverted.bg, theme.palette.inverted.fg
<Box tm='inverted' /> // background-color: #222222; color: #fffffff

// Valid color value
<Box bg="#ffff00" /> // background-color: #ffff00

box

import { box } from 'pss'

Combination of

Related: boxStyle, combineStyles.

Parameters

Examples

import { box } from 'pss'

const Box = styled.p`
  ${box}
`
<Box mx='auto' /> // → marginLeft: auto; marginRight: auto
<Box flex='1 1 0' /> // → flex: 1 1 0
<Box width={1 / 2} /> // → width: 50%

boxStyle

import { boxStyle } from 'pss'

Global box styles system, like in Sketch.

Related: variant.

Add boxStyle to theme:

const theme = {
  boxStyle: {
    red: {
      backgroundColor: 'red',
      color: 'white'
    },
    shadow: {
      boxShadow: '0 0 20px 0 rgba(0, 0, 0, .3)'
    }
  }
}

Parameters

Examples

import { boxStyle } from 'pss'

const Box = styled.div`
  ${boxStyle}
`
<Box boxStyle='red' /> // → background-color: red; color: white;
<Box boxStyle='shadow' /> // → box-shadow: 0 0 20px 0 rgba(0, 0, 0, .3);
const Box = styled.div`
  ${boxStyle.variant}
`

<Box variant='red' /> // → background-color: red; color: white;
<Box variant='shadow'  /> // → box-shadow: 0 0 20px 0 rgba(0, 0,

text

import { text } from 'pss'

Combination of

Related: textStyle, combineStyles.

Parameters

Examples

import { text } from 'pss'

const Text = styled.p`
  ${text}
`
<Text textAlign='center' /> // text-align: center
<Text lineHeight='normal' /> // line-height: normal

textStyle

import { textStyle } from 'pss'

Global text styles system, like in Sketch.

Related: variant, text.

Add textStyle to theme:

const theme = {
  textStyle: {
    default: {
      fontSize: '16px',
      lineHeight: 1.2,
      fontWeight: 'normal',
      fontFamily: 'system-ui'
    },
    heading: {
      fontSize: '2rem',
      lineHeight: 1.2,
      fontWeight: 'bold',
      fontFamily: 'system-ui'
    }
  }
}

Parameters

Examples

import { textStyle } from 'pss'

const Box = styled.div`
  ${textStyle}
`
<Box textStyle='auto' /> // → `theme.textStyle.default`
<Box textStyle='heading' /> // → `theme.textStyle.heading`
const Text = styled.div`
  ${textStyle.variant}
`

<Text variant='auto' /> // → `theme.textStyle.default`
<Text variant='heading' /> // → `theme.textStyle.heading`

Styles

border

import { border } from 'pss'

Set border with values from theme.

prop css theme value default
border border border ✓ theme.border.default
borderLeft border-left border ✓ theme.border.default
borderRight border-right border ✓ theme.border.default
borderTop border-top border ✓ theme.border.default
borderBottom border-bottom border ✓ theme.border.default

Related: themeValue, rule,

Parameters

Examples

import { border } from 'pss'

const Box = styled.div`
  ${border}
`
<Box border='1px dotted red' /> // → border: 1px dotted red
<Box borderBottom='divider' /> // → theme.border.divider // → border-bottom: 1px dotted #f5f5f5

borderColor

import { borderColor } from 'pss'
prop css theme value default
borderColor border-color color, palette.*.border ✓ theme.palette.default.border

Related: colorValue, style,

Parameters

Examples

import { border, borderColor } from 'pss'

const Box = styled.div`
  ${border}
  ${borderColor}
`
<Box borderBottom='thick' borderColor='red' /> // border-left: 3px solid; border-color: red

borderRadius

import { borderRadius } from 'pss'
prop css theme value default
borderRadius border-radius borderRadius ✓ theme.borderRadius.default

Related: style.

Parameters

Examples

import { borderRadius } from 'pss'

const Box = styled.div`
  ${borderRadius}
`
<Box borderRadius='5px' /> // → border-radius: 5px
<Box borderRadius='round' /> // → `theme.borderRadius.round` → border-radius: 9999px

boxContentAlignment

import { boxContentAlignment } from 'pss'
prop css theme value default
alignContent align-content — ✓ —
justifyContent justify-content — ✓ —

Related: rule

Parameters

Examples

import { boxContentAlignment } from 'pss'

const Grid = styled.div`
  display: grid;
  ${boxContentAlignment}
`
<Grid alignContent='center'>
  <div>1</div>
  <div>2</div>
</Grid>

boxItemsAlignment

import { boxItemsAlignment } from 'pss'
prop css theme value default
alignItems align-items — ✓ —
justifyItems justify-items — ✓ —

Related: rule

Parameters

Examples

import { boxItemsAlignment } from 'pss'

const Grid = styled.div`
  display: grid;
  ${boxItemsAlignment}
`
<Grid alignItems='center'>
  <div>1</div>
  <div>2</div>
</Grid>

boxSelfAlignment

import { boxSelfAlignment } from 'pss'
prop css theme value default
alignSelf align-self — ✓ —
justifySelf justify-self — ✓ —

Related: rule

Parameters

Examples

import { boxSelfAlignment } from 'pss'

const Box = styled.div`
  ${boxSelfAlignment}
`
<Grid>
  <Box alignSelf='center'>1</Box>
</Grid>

boxShadow

import { boxShadow } from 'pss'
prop css theme value default
boxShadow box-shadow boxShadow ✓ theme.boxShadow.default

Related: box, style, themeValue.

Parameters

Examples

import { boxShadow } from 'pss'

const Box = styled.p`
  ${boxShadow}
`
<Box boxShadow='0 0 10px rgba(0, 0, 0, 0.1)' /> // → box-shadow: 0 0 10px rgba(0, 0, 0, 0.1)
<Box boxShadow='elevate-100' /> // → theme.boxShadow['elevate-100']
<Box boxShadow='auto' /> // → theme.boxShadow.default
<Box boxShadow /> // → theme.boxShadow.default

display

import { display } from 'pss'
prop css theme value default
display display — ✓ —

Related: hide, rule.

Parameters

Examples

import { display } from 'pss'

const Box = styled.div`
  ${display}
`
<Box display='inline-block' /> // display: inline-block;

flex

import { flex } from 'pss'
prop css theme value default
flex flex size ✓ —

Related: rule, sizeValue.

Examples

import { flex } from 'pss'

const Box = styled.div`
  ${flex}
`
<FlexBox> // display: flex
  <Box flex='1 1 auto'>2</Box> // flex: 1 1 auto
</FlexBox>

flexContainer

import { flexContainer } from 'pss'

Flexible Box Layout Container styles. For alignment use boxContentAlignment, boxItemsAlignment.

prop css theme value default
flexWrap flex-wrap — ✓ —
flexDirection flex-direction — ✓ —

Related: rule.

Parameters

Examples

import { flexContainer } from 'pss'

const Flex = styled.div`
  display: flex;
  ${flexContainer}
`
<Flex flexDirection='column' flexWrap='wrap'> // display: flex; flex-direction: column; flex-wrap: wrap;
  <div>1</div>
  <div>2</div>
</Flex>

fontFamily

import { fontFamily } from 'pss'
prop css theme value default
fontFamily font-family fontFamily ✓ theme.fontFamily.default

Related: text, ellipsis, rule, themeValue.

Set font-family from theme:

const theme = {
  default: {
    fontFamily: 'ui' // this can be changed in runtime, default to `default`
  },
  fontFamily: {
    heading: 'Times',
    ui: 'Helvetica'
  }
}

Related: style.

Parameters

Examples

import { fontFamily } from 'pss'

const Text = styled.p`
  ${fontFamily}
`
<Text fontFamily /> // → font-family: Helvetica
<Text fontFamily='auto' /> // → font-family: Helvetica
<Text fontFamily='ui' /> // → font-family: Helvetica
<Text fontFamily='heading' /> // → font-family: Times
<Text fontFamily='Comic Sans' /> // → font-family: Comic Sans

fontSize

import { fontSize } from 'pss'
prop css theme value default
fontSize font-size fontSize ✓ theme.fontSize.default

Related: text, ellipsis, rule, themeValue.

const theme = {
  default: {
    fontSize: 'root' // this can be changed in runtime, default to `default`
  },
  media: {
    sm: '(max-width: 600px)'
  },
  fontSize: {
    root: 16,
    heading: 22,
    caption: {
      all: 12,
      sm: 14
    }
  }
}

Parameters

Examples

import { fontSize } from 'pss'

const Text = styled.p`
  ${fontSize}
`
<Text fontSize='1rem' /> // → font-size: 1rem
<Text fontSize='root' /> // → theme.fontSize.root // → font-size: 1rem
<Text fontSize='heading' /> // → theme.fontSize.heading // → font-size: 1.5rem
<Text fontSize='auto' /> // → theme.fontSize.root // → font-size: 1rem

fontWeight

import { fontWeight } from 'pss'
prop css theme value default
fontWeight font-weight — ✓ —

Related: text, ellipsis, rule

Parameters

Examples

import { fontWeight } from 'pss'

const Text = styled.p`
  ${fontWeight}
`
<Text fontWeight='bold' /> // font-weight: bold

gap

import { gap } from 'pss'

Same as space but for grid and flex.

Component props:

  • gap → grid-gap, gap
  • columnGap → grid-column-gap, column-gap
  • rowGap → grid-row-gap, row-gap

Parameters

Examples

import { gap } from 'pss'

const Grid = styled.div`
  display: grid;
  ${gap}
`
<Grid gap={1}> // grid-gap: 4px; gap: 4px
 <div>1</div>
 <div>2</div>
</Grid>

gridContainer

import { gridContainer } from 'pss'

Grid Layout Container styles.

prop css theme value default
grid grid — ✓ —
gridAutoFlow grid-auto-flow — ✓ —
gridAutoColumns grid-auto-columns — ✓ —
gridAutoRows grid-auto-rows — ✓ —
gridTemplate grid-template gridTemplate ✓ theme.gridTemplate.default
gridTemplateColumns grid-template-columns — ✓ —
gridTemplateRows grid-template-rows — ✓ —
gridTemplateAreas grid-template-areas — ✓ —

Related: gap, flex, rule

Parameters

Examples

import { gridContainer } from 'pss'

const Grid = styled.div`
  display: grid;
  ${gridContainer}
`
<Grid gridTemplateColumns='repeat(12, 1fr)'> // display: grid; grid-template-columns: repeat(12, 1fr)
  <div>1</div>
  <div>2</div>
</Grid>

gridItem

import { gridItem } from 'pss'
prop css theme value default
gridColumn grid-column — ✓ —
gridRow grid-row — ✓ —
gridArea grod-area — ✓ —

Related: rule, sizeValue.

Examples

import { gridItem } from 'pss'

const GridItem = styled.div`
  ${gridItem}
`
<Grid> // display: grid
  <GridItem gridRow='1' girdColumn='2'>1</GridItem>
  <GridItem gridRow='2' gridColumn='1'>2</GridItem>
</Grid>

hide

import { hide } from 'pss'
prop css theme value default
hide display: none media key from theme.media apply style

Related: display, mediaStyle.

Parameters

Examples

import { hide } from 'pss'

const Box = styled.div`
  ${hide}
`
<Box hide />
// → display: none

<Box hide='sm' />
// → @media (max-width: 600px) { display: none }

<Box hide={{ sm: true, md: true }} />
// → @media (max-width: 600px) { display: none }
// → @media (min-width: 601px) and (max-width: 1024px) { display: none }

letterSpacing

import { letterSpacing } from 'pss'
prop css theme value default
letterSpacing letter-spacing — ✓ —

Related: text, ellipsis, rule.

Parameters

Examples

import { letterSpacing } from 'pss'

const Text = styled.p`
  ${letterSpacing}
`
<Text letterSpacing='-0.15em' /> // letter-spacing: -0.15em

lineHeight

import { lineHeight } from 'pss'
prop css theme value default
lineHeight line-height — ✓ —

Related: text, ellipsis, rule.

Parameters

Examples

import { lineHeight } from 'pss'

const Text = styled.p`
  ${lineHeight}
`
<Text lineHeight={1.5} /> // line-height: 1.5

margin

import { margin } from 'pss'

Margin space system.

Parameters

Examples

import { margin } from 'pss'

const Box = styled.div`
  ${margin}
`
<Box margin={1} /> // → margin: 4px
<Box marginLeft={0} /> // → margin-left: 0
<Box marginRight='auto' /> // → margin-right: auto
<Box marginTop='8px' /> // → margin-top: 8px
<Box marginBottom={3} /> // → margin-top: 16px

opacity

import { opacity } from 'pss'
prop css theme value default
opacity opacity — 0...1 —

Related: rule.

Parameters

Examples

import { opacity } from 'pss'

const Box = styled.div`
  ${opacity}
`
<Box opacity='1' /> // → opacity: 1
<Box opacity={0.5} /> // → opacity: 0.5

order

import { order } from 'pss'
prop css theme value default
order order — ✓ —

Related: rule, sizeValue.

Parameters

Examples

import { order } from 'pss'

const Box = styled.div`
  ${order}
`
<FlexBox> // display: flex
  <Box>2</Box>
  <Box order={1}>1</Box>
</FlexBox>

outline

import { outline } from 'pss'
prop css theme value default
outline outline — ✓ —

* Random hex color, useful for debugging layout

Related: rule.

Parameters

Examples

import { outline } from 'pss'

const Box = styled.div`
  ${outline}
`
<Box outline='1px solid red' /> // → outline: 1px solid red

overflow

import { overflow } from 'pss'

Shorthand for overflow-x, overflow-y and -webkit-overflow-scrolling.

Related: style.

Parameters

Examples

import { overflow } from 'pss'

const Box = styled.div`
  ${overflow}
`
<Box overflow='hidden' /> // overflow: hidden
<Box overflow='hidden auto' /> // overflow-x: hidden; overflow-y: auto
<Box overflow='auto touch' /> // overflow: auto; -webkit-overflow-scrolling: touch

padding

import { padding } from 'pss'

Padding space space system.

Parameters

Examples

import { padding } from 'pss'

const Box = styled.div`
  ${padding}
`
<Box padding={1} /> // → padding: 4px
<Box paddingLeft={0} /> // → padding-left: 0
<Box paddingRight='auto' /> // → padding-right: auto
<Box paddingTop='8px' /> // → padding-top: 8px
<Box paddingBottom={3} /> // → padding-top: 16px

position

import { position } from 'pss'
prop css theme value default
position position — ✓ —

Related: rule, positionOffsets.

Parameters

Examples

import { position, positionOffsets } from 'pss'

const Box = styled.div`
  ${position}
  ${positionOffsets}
`
<Box position='absolute' top={0.2} left={0} /> // position: absolute; top: 20%; left: 0

positionOffsets

import { positionOffsets } from 'pss'
prop css theme value default
left left size ✓ —
right right size ✓ —
top top size ✓ —
bottom bottom size ✓ —

Related: position, rule, sizeValue.

Parameters

Examples

import { positionOffsets } from 'pss'

const Box = styled.div`
  position: relative;
  ${positionOffsets}
`
<Box top={1 / 5} left={0} /> // position: relative; top: 20%; left: 0

ratio

import { ratio } from 'pss'

Aspect Ratio Box prop style with pseudo elements.

Parameters

Examples

import { ratio } from 'pss'

const Box = styled.div`
  ${ratio}
`
<Box ratio={(16 / 9)} />

.css::before {
  content: '';
  width: 1px;
  margin-left: -1px;
  float: left;
  height: 0;
  padding-bottom: 56.25%;
}

.css::after {
  content: '';
  display: table;
  clear: both;
}

textAlign

import { textAlign } from 'pss'
prop css theme value default
textAlign text-align — ✓ —

Related: text, ellipsis, rule.

Parameters

Examples

import { textAlign } from 'pss'

const Text = styled.p`
  ${textAlign}
`
<Text textAlign='center' /> // text-align: center

textColor

import { textColor } from 'pss'
prop css theme value default
color color color, palette.*.fg ✓ theme.palette.default.fg

Related: backgroundColor, colors, style, colorValue.

Examples use this theme:

const theme = {
  default: {
    palette: 'default' // this can be changed in runtime and default to `default`
  },
  color: {
    red: '#ff0000',
    black: '#222222',
    white: '#ffffff'
  },
  palette: {
    default: { // currently active
      fg: '#000000',
      accent: '#ff0000'
    },
    inverted: {
      fg: '#ffffff',
      accent: '#ff0000'
    }
  }
}

Parameters

Examples

import { textColor } from 'pss'

const Box = styled.div`
  ${textColor}
`
// theme.colors.black
<Box color='black' /> // color: #222222

// theme.palette.default.accent
<Box color='accent' /> // color: #ff0000

// Get default value from `theme.palette.default.fg`
<Box color='auto' /> // color: #000000
<Box color /> // color: #000000

// Valid color value
<Box color="#ffff00" /> // background-color: #ffff00

textOverflow

import { ellipsis } from 'pss'

Info: text-overflow.

Related: rule.

Parameters

Examples

import { textOverflow } from 'pss'

const Text = styled.p`
  ${textOverflow}
`
<Text textOverflow='ellipsis' /> // → white-space: nowrap; overflow: hidden; text-overflow: ellipsis;

transform

import { transform } from 'pss'
prop css theme value default
transform transform — ✓ —

Related: rule.

Parameters

Examples

import { transform } from 'pss'

const Box = styled.div`
  ${transform}
`
<Box transform='rotate(90deg)' /> // → transform: rotate(90deg)

transition

import { transition } from 'pss'
prop css theme value default
transition transition — ✓ —

Related: rule.

Parameters

Examples

import { transition } from 'pss'

const Box = styled.div`
  ${transition}
`
<Box transition='all .3s' /> // → transition: all .3s

whiteSpace

import { whiteSpace } from 'pss'
prop css theme value default
whiteSpace white-space — ✓ —

Related: text, ellipsis, style.

Parameters

Examples

import { whiteSpace } from 'pss'

const Text = styled.p`
  ${whiteSpace}
`
<Text whiteSpace='nowrap' /> // white-space: nowrap

zIndex

import { zIndex } from 'pss'
prop css theme value default
zIndex z-index zIndex ✓ —

Related: position, rule, style.

Parameters

Examples

import { zIndex } from 'pss'

const Box = styled.div`
  position: relative;
  ${zIndex}
`
<Box zIndex={10} /> // position: relative; z-index: 10;
<Box zIndex='modal' /> // position: relative; z-index: 100;

atomic

import { atomic } from 'pss'

First version of pss is different, most of the styles applied with short flags. Now this variants considered as bad practice as it introduce new syntax to rembember. But sometimes it can be useful to have short variants and can speed-up development process.

prop css theme value default
d display — ✓ —
f flex — ✓ —
o order — ✓ —
prl position: relative media key from theme.media appy style
pab position: absolute media key from theme.media appy style
pfx position: fixed media key from theme.media appy style
psy position: sticky media key from theme.media appy style
pst position: static media key from theme.media appy style
l left sizes ✓ 0
r right sizes ✓ 0
t top sizes ✓ 0
b bottom sizes ✓ 0
x left, right sizes ✓ 0
y top, bottom sizes ✓ 0
z z-index zIndex ✓ 1
w width sizes ✓ 100%
h height sizes ✓ 100%
minw min-width sizes ✓ 100%
minh min-height sizes ✓ 100%
maxw max-width sizes ✓ 100%
maxh max-height sizes ✓ 100%
ov overflow — ✓ auto

Related space, colors, hide.

Parameters

Examples

import { atomic } from 'pss'

const Box = styled.div`
  ${atomic}
`
<Box d='inline-block' /> // → display: inline-block;
<Box d='flex'> // → display: inline-block;
  <Box f='1' o='1'> // → flex: 1; order: 1
     Second
  </Box>
  <Box>
   First
  </Box>
</Box>

<Box w h /> // → width: 100%; height: 100%;
<Box minw={1 / 4} /> // → min-width: 25%
<Box prl /> // → position: relative;
<Box pab='sm' /> // → @media (max-width: 600px) { position: absolute; }
<Box t={0.2} l={0} /> // → position: absolute; top: 20%; left: 0
<Box x y /> // → position: absolute; top: 0; left: 0; right: 0; bottom: 0;
<Box ov='auto touch' /> // → overflow: auto; -webkit-overflow-scrolling: touch

Mixins

themePath

import { themePath } from 'pss'

Get value from theme. Optionally accept fallback and / or list of transforms.

Parameters

  • input
  • defaultValue
  • fns ...any

Examples

import { themePath, px } from 'pss'

const Box = styled.div`
  width: ${themePath('size.card', px)};
  background-color: ${themePath('color.red', 'hotpink')};
`

<Box /> // → width: 200px; background-color: hotpink;

mq

import { mq } from 'pss'

Parameters

  • mediaKey — key in theme.media
  • fallback (optional, default 'all')

Examples

import { mq, themePath } from 'pss'

const Box = styled.div`
  @media ${mq('sm')} {
    background-color: ${themePath('color.red', 'hotpink')};
  }
`

<Box /> // → @media (max-width: 600px) { background-color: red; }

prop

import { prop } from 'pss'

Parameters

  • key
  • fallback

Examples

import { prop, themePath, mq } from 'pss'

const Box = styled.div`
 background-color: ${prop('bg')};
 color: ${prop('color', themePath('color.primary'))};
 border-color: ${prop('borderColor', 'black')};
 width: ${prop('width', '100%')};

 @media ${mq('sm')} {
   width: ${prop('width.sm'};
 }
`

<Box bg='red' /> // → background-color: red; color: #0000FF; border-color: black;
<Box color='blue' /> // → color: blue; border-color: black;

Utils

combineStyles

Combine multiple styles together

Parameters

  • fns ...any

Examples

import { combineStyles } from 'pss'
import { combineStyles, margin, padding } from 'pss'

const space = combineStyles(
  margin,
  padding
)

const Space = styled.div`
  ${space}
`

rem

Convert number to rem

Parameters

  • base number root font size (optional, default 16)
  • input number value for convertion (optional, default base)

Examples

import { rem } form 'pss'

rem(16, 16) // → 1rem
rem(16, 20) // → 1.25rem
rem(16, '20px') // → 1.25rem

const myRem = rem(20)
myRem(16) // → 0.8rem

px

Convert numbers to pixels

Parameters

  • num

Examples

import { px } from 'pss'

px(30) // → '30px'
px(0) // → 0
px('100px') // → '100px'
px('100rem') // → '100rem' (nothing changed)

splitUnit

Parameters

  • input

Examples

import { splitUnit } from 'pss'

const [ value, unit ] = splitUnit('30px') // → [ 30, 'px' ]

getPropTypes

Return prop types for styles created with pss.

Must have prop-types installed in project.

Parameters

  • input

Examples

import { sizes } from 'pss'
import { getPropTypes } from 'pss/prop-types'

cont Box = styled('div')`
  ${sizes}
`

Box.propTypes = {
  ...getPropTypes(sizes)
}

Custom Styles

createStyles

import pss from 'pss'
import { createStyles } from 'pss'

Create styles from Object with keys that represents component prop and the value is a style that will be applied.

{ [prop]: style | (input, props, mediaKey) => style }
  • input - prop value
  • props Object - component props, including theme
  • mediaKey Object - key in theme.media

In component prop accepts values:

  • Boolean — enable / disable simple styles or default variant

    const Comp = styled.div(createStyles({ red: { color: 'red' } }))

<Comp red /> // → color: red
<Comp red={false} /> // → 🤷‍♂️

  • Boolean, String, Number — handled in functional styles

    const Comp = styled.div(createStyles({ width: (input) => ({ width: input } })))

<Comp width='100px' /> // → width: 100px

  • Object with keys defined in theme.media to define values for different screen sizes

    <Comp width={{ all: '100px', sm: '50px' }} /> // → width: 100px; @media (max-width: 600px) { width: 50px }

Parameters

Examples

import { createStyles } from 'pss'

const styles = createStyles({
  display: value => ({ display: value }),
  hide: { display: 'none' },
  width: (value, props, mediaKey) => ({
    width: mediaKey === 'sm' && value === true ? '100%' : value
  })
})

const Box = styled.div`
  ${styles}
`
<Box display='inline-flex' /> // → display: inline-flex
<Box hide /> // → display: none
// Add media queries
const theme = {
  media: {
    sm: '(max-width: 600px)'
  }
}

<Box theme={theme} width={{ all: '100px', sm: true }} /> // → width: 100px; @media (max-width: 600px) { width: 100% }

<ThemeProvider theme={theme}>
  <Box display='flex' hide={{ sm: true }} /> // → display: flex; @media (max-width: 600px) { display: none }
</ThemeProvider>

Returns Function (props) => styles

rule

import { rule } from 'pss'

Create style rule. Must be used with createStyles.

Parameters

Examples

import pss, { rule } from 'pss'

const Box = styled.div(pss({
  display: rule('display')
}))
// Add theme to ThemeProvider
<ThemeProvider theme={theme}>
  <Box display='flex' /> // → display: flex
</ThemeProvider>

Returns Function

boolValue

import { boolValue } from 'pss'

Get value for rule based boolean condition, other values passed without modification. Must be used with rule.

Parameters

  • trueValue
  • falseValue
  • defaultValue

Examples

import pss, { rule, boolValue } from 'pss'

const Box = styled.div(pss({
  opacity: rule('opacity', boolValue(1, 0))
}))
<Box opacity /> // → opacity: 1
<Box opacity={false} /> // → opacity: 0
<Box opacity={0.5} /> // → opacity: 0.5

sizeValue

import { sizeValue } from 'pss'

Sizes system for any css prop. Default behaviour described in sizes. Must be used with rule.

Created with themeValue:

const sizeValue = themeValue({
  transformValue: px,
  fallback: (input) => px(input),
  themeKey: 'size'
})

Related: sizes, rule, spaceValue, px.

Parameters

Examples

import pss, { rule, sizeValue, boolValue } from 'pss'

const sizes = pss({
  h: rule('height', sizeValue())
  w: rule('width', sizeValue()),
  l: rule('left', sizeValue(boolValue(0))),
  r: rule('right', sizeValue(boolValue(0)))
})

const Box = styled.div`
  ${sizes}
`
<Box w={0} /> // → width: 0
<Box h='300px' /> // → height: 300px
<Box l={{ all: 0, sm: 'auto' }} /> // → left: 0; @media (max-width: 600px) { left: auto }
<Box l={20} r={10} /> // → left: 20px; right: 10px
<Box l r /> // → left: 0; right: 0

Returns Function that must be used in rule

percentageValue

import { percentageValue } from 'pss'

Related: sizes, rule, sizeValue.

Examples

import pss, { rule, percentageValue } from 'pss'

const sizes = pss({
  w: rule('width', percentageValue())
})

const Box = styled.div`
  ${sizes}
`
<Box w={1} /> // → width: 100%
<Box w={1 / 2} /> // → width: 50%
<Box w={0} /> // → width: 0
<Box w={100} /> // → width: 100px

Returns Function that must be used in rule

spaceValue

import { spaceValue } from 'pss'

Spacing system for margin, padding. Default behaviour described in space. Must be used with rule.

Related: space, sizes, rule, sizeValue.

Parameters

  • defaultValue — Fallback value used when prop value is String or nothing returned. (optional, default sizeValue(identity))

Examples

import pss, { rule, spaceValue } from 'pss'

const spaceRule = (name) => rule(name, spaceValue())

const margin = pss({
  m: spaceRule('margin'),
  ml: spaceRule('marginLeft'),
  mr: spaceRule('marginRight'),
  mt: spaceRule('marginTop'),
  mb: spaceRule('marginBottom'),
  mx: [ spaceRule('marginLeft'), spaceRule('marginRight') ],
  my: [ spaceRule('marginTop'), spaceRule('marginBottom') ]
})

const Box = styled.div`
  ${margin}
`
const theme = {
  media: {
    sm: '(max-width: 600px)' // optional
  },
  space: [ 0, 8, 16, 32, 64 ]
}

<ThemeProvider theme={theme}>
  <Box m={1} /> // → margin: 8px;
  <Box mx={2} /> // → margin-left: 16px; margin-right: 16px
  <Box m={{ sm: 1 }} /> // → @media (max-width: 600px) { margin: 8px }
</ThemeProvider>
const theme = {
  media: {
    sm: '(max-width: 600px)'
  },
  space: {
    all: [ 0, 8, 16, 32, 64 ],
    sm: [ 0, 4, 8, 16, 32 ]
  }
}

<ThemeProvider theme={theme}>
  <Box m={1} /> // → margin: 8px; @media (max-width: 600px) { margin: 4px }
  <Box mx={2} /> // → margin-left: 16px; margin-right: 16px; @media (max-width: 600px) { margin-left: 8px; margin-right: 8px; }
  <Box m={{ sm: 1 }} /> // → @media (max-width: 600px) { margin: 4px }
</ThemeProvider>

Returns Function that must be used in rule

colorValue

import { colorValue } from 'pss'

Get color from theme and apply it to css prop. Must be used with rule.

Parameters

  • key string — Key in theme.color or in theme.palette[theme.default.palette]
  • transformValue Function — Return customized CSS prop value (i.e. box-shadow, gradients) (optional, default identity)

Examples

import pss, { rule, colorValue } from 'pss'

const colors = pss({
  fg: rule('color', colorValue('fg')),
  bg: rule('backgroundColor', colorValue('bg')),
  shadow: rule('boxShadow', colorValue('shadow', (color) => `0 0 20px 0 ${color}`)),
  tm: [
     rule('color', colorValue('fg')),
     rule('backgroundColor', colorValue('bg'))
  ]
})

// Add to component
const Box = styled.div`
  ${colors}
`
// theme.palette.default.fg
<Box fg='auto' /> // background-color: #222222
<Box fg /> // background-color: #222222

// theme.colors.black
<Box fg='black' /> // color: #222222

// theme.palette.default.accent
<Box fg='accent' /> // color: #ff0000

// theme.palette.default.shadow
<Box shadow='auto' /> // box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.2)
<Box shadow /> // box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.2)

// theme.palette.default.fg, theme.palette.default.bg
<Box tm='default' /> // color: #222222; background-color: #ffffff

Returns Function

themeValue

import { themeValue } from 'pss'

Use values defined in theme[themeKey].

See fontFamily, radius.

Parameters

  • options Object (optional, default {})
    • options.themeKey
    • options.transformValue (optional, default identity)
    • options.fallback
    • options.scale (optional, default {})
    • options.defaultKeyword (optional, default 'auto')

Examples

const theme = {
  font: {
    heading: 'Times New Roman, serif',
    ui: 'system-ui, Helvetica, sans-serif'
  }
}
import pss, { themeValue } from 'pss'

const Text = styled.div(pss({
  fontFamily: rule('fontFamily', themeValue({ themeKey: 'font' }))
}))

<ThemeProvider theme={theme}>
  <Text fontFamily='ui'> // → font-family: system-ui, Helvetica, sans-serif
    Hello World!
  </Text>
</ThemeProvider>

Returns Function

mediaStyle

import { mediaStyle } from 'pss'

Create style wrapped in theme.media.

Related: display.

Parameters

  • style

Examples

import pss, { mediaStyle } from 'pss'

const Box = styled.div(pss({
  hide: mediaStyle({ display: 'none' })
}))
// Create theme with media queries
const theme = {
  media: {
    sm: '(max-width: 600px)'
  }
}

<ThemeProvider theme={theme}>
  <Box hide='sm' /> // @media (max-width: 600px) { display: 'none' }
</ThemeProvider>

createRule

import { createRule } from 'pss'

Create style from value. Must be used with createStyles.

Related: rule.

Parameters

  • options Object
    • options.cssProp
    • options.getStyle (optional, default wrap(cssProp))
    • options.getValue (optional, default identity)

Examples

import pss, { createRule, spaceValue } from 'pss'

const Box = styled.div(pss({
  gap: createRule({
    getStyle: (val) => ({ margin: val, padding: val }),
    getValue: spaceValue()
  })
}))
// Add theme to ThemeProvider
<ThemeProvider theme={theme}>
  <Box gap={1} /> // → margin: 8px; padding: 8px;
</ThemeProvider>

variant

Create variant from styles defined directly in theme. Inspired by styled-system.

Related: textStyle, boxStyle, rule, themeValue.

Parameters

  • options Object
    • options.prop String (optional, default 'variant')
    • options.defaultKeyword
    • options.themeKey
    • options.transformValue
    • options.scale
    • options.getter

Examples

import { variant } from 'pss'

const variant = variant({
  themeKey: 'textStyle'
})

const Text = styled.p`
  ${variant}
`
const theme = {
  textStyle: {
    default: {
      fontSize: '16px',
      lineHeight: 1.2,
      fontWeight: normal,
      fontFamily: 'system-ui'
    },
    heading: {
      fontSize: '2rem',
      lineHeight: 1.2,
      fontWeight: 'bold',
      fontFamily: 'system-ui'
    }
  }
}

<Text variant='default' /> // → `theme.textStyle.default`
<Text variant='heading' /> // → `theme.textStyle.heading`
const themeWithDefault = {
  default: {
     textStyle: 'default',
  },
  ...theme,
}

<Text variant='auto' /> // → `theme.textStyle.default`
<Text variant /> // → `theme.textStyle.default`

style

import { style } from 'pss'

Create style for single prop. Combines createStyles and createRule in single function. Inspired by styled-system.

Parameters

  • options Object
    • options.cssProp
    • options.themeKey
    • options.transformValue
    • options.scale
    • options.getter
    • options.prop (optional, default cssProp)
    • options.getValue (optional, default themeKey?themeValue({themeKey,transformValue,scale,getter}):undefined)

Examples

import pss, { style } from 'pss'

const opacity = style({
  cssProp: 'opacity'
})

const Box = styled.div`
  ${opacity}
`
<Box opacity={0.5} /> // → opacity: 0.5