Installation

npm install --save polished

Usage

import { lighten, modularScale } from 'polished'

Mixins

CSS to contain a float (credit to CSSMojo).

clearFix(parent: string?): Object
Parameters
parent (string? = '&')
Returns
Object
Example
// Styles as object usage
const styles = {
   ...clearFix(),
}

// styled-components usage
const div = styled.div`
  ${clearFix()}
`

// CSS as JS Output

'&::after': {
  'clear': 'both',
  'content': '""',
  'display': 'table'
}

CSS to represent truncated text with an ellipsis.

ellipsis(width: (string | number)?): Object
Parameters
width ((string | number)? = '100%')
Returns
Object
Example
// Styles as object usage
const styles = {
  ...ellipsis('250px')
}

// styled-components usage
const div = styled.div`
  ${ellipsis('250px')}
`

// CSS as JS Output

div: {
  'display': 'inline-block',
  'maxWidth': '250px',
  'overflow': 'hidden',
  'textOverflow': 'ellipsis',
  'whiteSpace': 'nowrap',
  'wordWrap': 'normal'
}

CSS for a @font-face declaration.

fontFace($0: Object): Object
Parameters
$0 (Object)
Name Description
$0.fontFamily any
$0.fontFilePath any
$0.fontStretch any
$0.fontStyle any
$0.fontVariant any
$0.fontWeight any
$0.fileFormats any (default ['eot', 'woff2', 'woff', 'ttf', 'svg'])
$0.localFonts any
$0.unicodeRange any
Returns
Object
Example
// Styles as object basic usage
const styles = {
   ...fontFace({
     'fontFamily': 'Sans-Pro'
     'fontFilePath': 'path/to/file'
   })
}

// styled-components basic usage
injectGlobal`${
  fontFace({
    'fontFamily': 'Sans-Pro'
    'fontFilePath': 'path/to/file'
  }
)}`

// CSS as JS Output

'@font-face': {
  'fontFamily': 'Sans-Pro',
  'src': 'url("path/to/file.eot"), url("path/to/file.woff2"), url("path/to/file.woff"), url("path/to/file.ttf"), url("path/to/file.svg")',
}

Generates a media query to target HiDPI devices.

hiDPI(ratio: number?): string
Parameters
ratio (number? = 1.3)
Returns
string
Example
// Styles as object usage
const styles = {
 [hiDPI(1.5)]: {
   width: 200px;
 }
}

// styled-components usage
const div = styled.div`
  ${hiDPI(1.5)} {
    width: 200px;
  }
`

// CSS as JS Output

'@media only screen and (-webkit-min-device-pixel-ratio: 1.5),
 only screen and (min--moz-device-pixel-ratio: 1.5),
 only screen and (-o-min-device-pixel-ratio: 1.5/1),
 only screen and (min-resolution: 144dpi),
 only screen and (min-resolution: 1.5dppx)': {
  'width': '200px',
}

CSS to hide text to show a background image in a SEO-friendly way.

hideText(): Object
Returns
Object
Example
// Styles as object usage
const styles = {
  'backgroundImage': 'url(logo.png)',
  ...hideText(),
}

// styled-components usage
const div = styled.div`
  backgroundImage: url(logo.png);
  ${hideText()};
`

// CSS as JS Output

'div': {
  'backgroundImage': 'url(logo.png)',
  'textIndent': '101%',
  'overflow': 'hidden',
  'whiteSpace': 'nowrap',
}

CSS to hide content visually but remain accessible to screen readers. from HTML5 Boilerplate

hideVisually(): Object
Returns
Object
Example
// Styles as object usage
const styles = {
  ...hideVisually(),
}

// styled-components usage
const div = styled.div`
  ${hideVisually()};
`

// CSS as JS Output

'div': {
  'border': '0',
  'clip': 'rect(0 0 0 0)',
  'clipPath': 'inset(50%)',
  'height': '1px',
  'margin': '-1px',
  'overflow': 'hidden',
  'padding': '0',
  'position': 'absolute',
  'whiteSpace': 'nowrap',
  'width': '1px',
}

CSS to normalize abnormalities across browsers (normalize.css v5.0.0 | MIT License | github.com/necolas/normalize.css)

normalize(excludeOpinionated: boolean): Object
Parameters
excludeOpinionated (boolean)
Returns
Object
Example
// Styles as object usage
const styles = {
   ...normalize(),
}

// styled-components usage
injectGlobal`${normalize()}`

// CSS as JS Output

html {
  fontFamily: 'sans-serif',
  lineHeight: 1.15,
  textSizeAdjust: 100%,
} ...

CSS to style the placeholder pseudo-element.

placeholder(styles: Object, parent: string?): Object
Parameters
styles (Object)
parent (string? = '&')
Returns
Object
Example
// Styles as object usage
const styles = {
  ...placeholder({'color': 'blue'})
}

// styled-components usage
const div = styled.input`
   ${placeholder({'color': 'blue'})}
`

// CSS as JS Output

'input': {
  '&:-moz-placeholder': {
    'color': 'blue',
  },
  '&:-ms-input-placeholder': {
    'color': 'blue',
  },
  '&::-moz-placeholder': {
    'color': 'blue',
  },
  '&::-webkit-input-placeholder': {
    'color': 'blue',
  },
},

CSS for declaring a radial gradient, including a fallback background-color. The fallback is either the first color-stop or an explicitly passed fallback color.

radialGradient($0: Object): Object
Parameters
$0 (Object)
Name Description
$0.colorStops any
$0.extent any
$0.fallback any
$0.position any
$0.shape any
Returns
Object
Example
// Styles as object usage
const styles = {
  ...radialGradient({
    colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
    extent: 'farthest-corner at 45px 45px',
    position: 'center',
    shape: 'ellipse',
  })
}

// styled-components usage
const div = styled.div`
  ${radialGradient({
    colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
    extent: 'farthest-corner at 45px 45px',
    position: 'center',
    shape: 'ellipse',
  })}
`

// CSS as JS Output

div: {
  'backgroundColor': '#00FFFF',
  'backgroundImage': 'radial-gradient(center ellipse farthest-corner at 45px 45px, #00FFFF 0%, rgba(0, 0, 255, 0) 50%, #0000FF 95%)',
}

A helper to generate a retina background image and non-retina background image. The retina background image will output to a HiDPI media query. The mixin uses a _2x.png filename suffix by default.

retinaImage(filename: string, backgroundSize: string, extension: string?, retinaFilename: string, retinaSuffix: string?): Object
Parameters
filename (string)
backgroundSize (string)
extension (string? = 'png')
retinaFilename (string)
retinaSuffix (string? = '_2x')
Returns
Object
Example
// Styles as object usage
const styles = {
 ...retinaImage('my-img')
}

// styled-components usage
const div = styled.div`
  ${retinaImage('my-img')}
`

// CSS as JS Output
div {
  backgroundImage: 'url(my-img.png)',
  '@media only screen and (-webkit-min-device-pixel-ratio: 1.3),
   only screen and (min--moz-device-pixel-ratio: 1.3),
   only screen and (-o-min-device-pixel-ratio: 1.3/1),
   only screen and (min-resolution: 144dpi),
   only screen and (min-resolution: 1.5dppx)': {
    backgroundImage: 'url(my-img_2x.png)',
  }
}

CSS to style the selection pseudo-element.

selection(styles: Object, parent: string?): Object
Parameters
styles (Object)
parent (string? = '')
Returns
Object
Example
// Styles as object usage
const styles = {
  ...selection({
    'backgroundColor': 'blue'
  }, 'section')
}

// styled-components usage
const div = styled.div`
  ${selection({'backgroundColor': 'blue'}, 'section')}
`

// CSS as JS Output

'div': {
  'section::-moz-selection': {
    'backgroundColor':'blue',
  },
  'section::selection': {
    'backgroundColor': 'blue',
  }
}

String to represent common easing functions as demonstrated here: (github.com/jaukia/easie).

timingFunctions(timingFunction: TimingFunction): string
Parameters
timingFunction (TimingFunction)
Returns
string
Example
// Styles as object usage
const styles = {
  'transitionTimingFunction': timingFunctions('easeInQuad')
}

// styled-components usage
 const div = styled.div`
  transitionTimingFunction: ${timingFunctions('easeInQuad')};
`

// CSS as JS Output

'div': {
  'transitionTimingFunction': 'cubic-bezier(0.550,  0.085, 0.680, 0.530)',
}

CSS to represent triangle with any pointing direction with an optional background color. Accepts number or px values for height and width.

triangle($0: Object): Object
Parameters
$0 (Object)
Name Description
$0.pointingDirection any
$0.height any
$0.width any
$0.foregroundColor any
$0.backgroundColor any (default 'transparent')
Returns
Object
Example
// Styles as object usage

const styles = {
  ...triangle({ pointingDirection: 'right', width: '100px', height: '100px', foregroundColor: 'red' })
}


// styled-components usage
const div = styled.div`
  ${triangle({ pointingDirection: 'right', width: '100px', height: '100px', foregroundColor: 'red' })}


// CSS as JS Output

div: {
 'borderColor': 'transparent',
 'borderLeftColor': 'red !important',
 'borderStyle': 'solid',
 'borderWidth': '50px 0 50px 100px',
 'height': '0',
 'width': '0',
}

Provides an easy way to change the wordWrap property.

wordWrap(wrap: string?): Object
Parameters
wrap (string? = 'break-word')
Returns
Object
Example
// Styles as object usage
const styles = {
  ...wordWrap('break-word')
}

// styled-components usage
const div = styled.div`
  ${wordWrap('break-word')}
`

// CSS as JS Output

const styles = {
  overflowWrap: 'break-word',
  wordWrap: 'break-word',
  wordBreak: 'break-all',
}

Color

Changes the hue of the color. Hue is a number between 0 to 360. The first argument for adjustHue is the amount of degrees the color is rotated along the color wheel.

adjustHue(degree: number, color: string): string
Parameters
degree (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: adjustHue(180, '#448'),
  background: adjustHue(180, 'rgba(101,100,205,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${adjustHue(180, '#448')};
  background: ${adjustHue(180, 'rgba(101,100,205,0.7)')};
`

// CSS in JS Output
element {
  background: "#888844";
  background: "rgba(136,136,68,0.7)";
}

Returns the complement of the provided color. This is identical to adjustHue(180, ).

complement(color: string): string
Parameters
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: complement('#448'),
  background: complement('rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${complement('#448')};
  background: ${complement('rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#884";
  background: "rgba(153,153,153,0.7)";
}

Returns a string value for the darkened color.

darken(amount: number, color: string): string
Parameters
amount (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: darken(0.2, '#FFCD64'),
  background: darken(0.2, 'rgba(255,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${darken(0.2, '#FFCD64')};
  background: ${darken(0.2, 'rgba(255,205,100,0.7)')};
`

// CSS in JS Output

element {
  background: "#ffbd31";
  background: "rgba(255,189,49,0.7)";
}

Decreases the intensity of a color. Its range is between 0 to 1. The first argument of the desaturate function is the amount by how much the color intensity should be decreased.

desaturate(amount: number, color: string): string
Parameters
amount (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: desaturate(0.2, '#CCCD64'),
  background: desaturate(0.2, 'rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${desaturate(0.2, '#CCCD64')};
  background: ${desaturate(0.2, 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#b8b979";
  background: "rgba(184,185,121,0.7)";
}

Returns a number (float) representing the luminance of a color.

getLuminance(color: string): number
Parameters
color (string)
Returns
number
Example
// Styles as object usage
const styles = {
  background: getLuminance('#CCCD64') >= getLuminance('#0000ff') ? '#CCCD64' : '#0000ff',
  background: getLuminance('rgba(58, 133, 255, 1)') >= getLuminance('rgba(255, 57, 149, 1)') ?
                            'rgba(58, 133, 255, 1)' :
                            'rgba(255, 57, 149, 1)',
}

// styled-components usage
const div = styled.div`
  background: ${getLuminance('#CCCD64') >= getLuminance('#0000ff') ? '#CCCD64' : '#0000ff'};
  background: ${getLuminance('rgba(58, 133, 255, 1)') >= getLuminance('rgba(255, 57, 149, 1)') ?
                            'rgba(58, 133, 255, 1)' :
                            'rgba(255, 57, 149, 1)'};

// CSS in JS Output

div {
  background: "#CCCD64";
  background: "rgba(58, 133, 255, 1)";
}

Converts the color to a grayscale, by reducing its saturation to 0.

grayscale(color: string): string
Parameters
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: grayscale('#CCCD64'),
  background: grayscale('rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${grayscale('#CCCD64')};
  background: ${grayscale('rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#999";
  background: "rgba(153,153,153,0.7)";
}

Returns a string value for the color. The returned result is the smallest possible hex notation.

hsl(value: (HslColor | number), saturation: number, lightness: number): string
Parameters
value ((HslColor | number))
saturation (number)
lightness (number)
Returns
string
Example
// Styles as object usage
const styles = {
  background: hsl(359, 0.75, 0.4),
  background: hsl({ hue: 360, saturation: 0.75, lightness: 0.4 }),
}

// styled-components usage
const div = styled.div`
  background: ${hsl(359, 0.75, 0.4)};
  background: ${hsl({ hue: 360, saturation: 0.75, lightness: 0.4 })};
`

// CSS in JS Output

element {
  background: "#b3191c";
  background: "#b3191c";
}

Returns a string value for the color. The returned result is the smallest possible rgba or hex notation.

hsla(value: (HslaColor | number), saturation: number, lightness: number, alpha: number): string
Parameters
value ((HslaColor | number))
saturation (number)
lightness (number)
alpha (number)
Returns
string
Example
// Styles as object usage
const styles = {
  background: hsla(359, 0.75, 0.4, 0.7),
  background: hsla({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0,7 }),
  background: hsla(359, 0.75, 0.4, 1),
}

// styled-components usage
const div = styled.div`
  background: ${hsla(359, 0.75, 0.4, 0.7)};
  background: ${hsla({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0,7 })};
  background: ${hsla(359, 0.75, 0.4, 1)};
`

// CSS in JS Output

element {
  background: "rgba(179,25,28,0.7)";
  background: "rgba(179,25,28,0.7)";
  background: "#b3191c";
}

Inverts the red, green and blue values of a color.

invert(color: string): string
Parameters
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: invert('#CCCD64'),
  background: invert('rgba(101,100,205,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${invert('#CCCD64')};
  background: ${invert('rgba(101,100,205,0.7)')};
`

// CSS in JS Output

element {
  background: "#33329b";
  background: "rgba(154,155,50,0.7)";
}

Returns a string value for the lightened color.

lighten(amount: number, color: string): string
Parameters
amount (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: lighten(0.2, '#CCCD64'),
  background: lighten(0.2, 'rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${lighten(0.2, '#FFCD64')};
  background: ${lighten(0.2, 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output

element {
  background: "#e5e6b1";
  background: "rgba(229,230,177,0.7)";
}

Mixes two colors together by calculating the average of each of the RGB components.

By default the weight is 0.5 meaning that half of the first color and half the second color should be used. Optionally the weight can be modified by providing a number as the first argument. 0.25 means that a quarter of the first color and three quarters of the second color should be used.

mix(weight: number?, color: string, otherColor: string): string
Parameters
weight (number? = 0.5)
color (string)
otherColor (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: mix(0.5, '#f00', '#00f')
  background: mix(0.25, '#f00', '#00f')
  background: mix(0.5, 'rgba(255, 0, 0, 0.5)', '#00f')
}

// styled-components usage
const div = styled.div`
  background: ${mix(0.5, '#f00', '#00f')};
  background: ${mix(0.25, '#f00', '#00f')};
  background: ${mix(0.5, 'rgba(255, 0, 0, 0.5)', '#00f')};
`

// CSS in JS Output

element {
  background: "#7f007f";
  background: "#3f00bf";
  background: "rgba(63, 0, 191, 0.75)";
}

Increases the opacity of a color. Its range for the amount is between 0 to 1.

opacify(amount: number, color: string): string
Parameters
amount (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: opacify(0.1, 'rgba(255, 255, 255, 0.9)');
  background: opacify(0.2, 'hsla(0, 0%, 100%, 0.5)'),
  background: opacify(0.5, 'rgba(255, 0, 0, 0.2)'),
}

// styled-components usage
const div = styled.div`
  background: ${opacify(0.1, 'rgba(255, 255, 255, 0.9)')};
  background: ${opacify(0.2, 'hsla(0, 0%, 100%, 0.5)')},
  background: ${opacify(0.5, 'rgba(255, 0, 0, 0.2)')},
`

// CSS in JS Output

element {
  background: "#fff";
  background: "rgba(255,255,255,0.7)";
  background: "rgba(255,0,0,0.7)";
}

Returns an HslColor or HslaColor object. This utility function is only useful if want to extract a color component. With the color util toColorString you can convert a HslColor or HslaColor object back to a string.

parseToHsl(color: string): (HslColor | HslaColor)
Parameters
color (string)
Returns
(HslColor | HslaColor)
Example
// Assigns `{ red: 255, green: 0, blue: 0 }` to color1
const color1 = 'rgb(255, 0, 0)';
// Assigns `{ red: 92, green: 102, blue: 112, alpha: 0.75 }` to color2
const color2 = 'hsla(210, 10%, 40%, 0.75)';

Returns an RgbColor or RgbaColor object. This utility function is only useful if want to extract a color component. With the color util toColorString you can convert a RgbColor or RgbaColor object back to a string.

parseToRgb(color: string): (RgbColor | RgbaColor)
Parameters
color (string)
Returns
(RgbColor | RgbaColor)
Example
// Assigns `{ red: 255, green: 0, blue: 0 }` to color1
const color1 = 'rgb(255, 0, 0)';
// Assigns `{ red: 92, green: 102, blue: 112, alpha: 0.75 }` to color2
const color2 = 'hsla(210, 10%, 40%, 0.75)';

Selects black or white for best contrast depending on the luminosity of the given color. Follows W3C specs for readability at https://www.w3.org/TR/WCAG20-TECHS/G18.html

readableColor(color: string): string
Parameters
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  color: readableColor('#000'),
  color: readableColor('papayawhip'),
  color: readableColor('rgb(255,0,0)'),
}

// styled-components usage
const div = styled.div`
  color: ${readableColor('#000')};
  color: ${readableColor('papayawhip')};
  color: ${readableColor('rgb(255,0,0)')};
`

// CSS in JS Output

element {
  color: "#fff";
  color: "#fff";
  color: "#000";
}

Returns a string value for the color. The returned result is the smallest possible hex notation.

rgb(value: (RgbColor | number), green: number, blue: number): string
Parameters
value ((RgbColor | number))
green (number)
blue (number)
Returns
string
Example
// Styles as object usage
const styles = {
  background: rgb(255, 205, 100),
  background: rgb({ red: 255, green: 205, blue: 100 }),
}

// styled-components usage
const div = styled.div`
  background: ${rgb(255, 205, 100)};
  background: ${rgb({ red: 255, green: 205, blue: 100 })};
`

// CSS in JS Output

element {
  background: "#ffcd64";
  background: "#ffcd64";
}

Returns a string value for the color. The returned result is the smallest possible rgba or hex notation.

Can also be used to fade a color by passing a hex value or named CSS color along with an alpha value.

rgba(firstValue: (RgbaColor | number | string), secondValue: number, thirdValue: number, fourthValue: number): string
Parameters
firstValue ((RgbaColor | number | string))
secondValue (number)
thirdValue (number)
fourthValue (number)
Returns
string
Example
// Styles as object usage
const styles = {
  background: rgba(255, 205, 100, 0.7),
  background: rgba({ red: 255, green: 205, blue: 100, alpha: 0.7 }),
  background: rgba(255, 205, 100, 1),
  background: rgba('#ffffff', 0.4),
  background: rgba('black', 0.7),
}

// styled-components usage
const div = styled.div`
  background: ${rgba(255, 205, 100, 0.7)};
  background: ${rgba({ red: 255, green: 205, blue: 100, alpha: 0.7 })};
  background: ${rgba(255, 205, 100, 1)};
  background: ${rgba('#ffffff', 0.4)};
  background: ${rgba('black', 0.7)};
`

// CSS in JS Output

element {
  background: "rgba(255,205,100,0.7)";
  background: "rgba(255,205,100,0.7)";
  background: "#ffcd64";
  background: "rgba(255,255,255,0.4)";
  background: "rgba(0,0,0,0.7)";
}

Increases the intensity of a color. Its range is between 0 to 1. The first argument of the saturate function is the amount by how much the color intensity should be increased.

saturate(amount: number, color: string): string
Parameters
amount (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: saturate(0.2, '#CCCD64'),
  background: saturate(0.2, 'rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${saturate(0.2, '#FFCD64')};
  background: ${saturate(0.2, 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output

element {
  background: "#e0e250";
  background: "rgba(224,226,80,0.7)";
}

Sets the hue of a color to the provided value. The hue range can be from 0 and 359.

setHue(hue: number, color: string): string
Parameters
hue (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: setHue(42, '#CCCD64'),
  background: setHue(244, 'rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${setHue(42, '#CCCD64')};
  background: ${setHue(244, 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#cdae64";
  background: "rgba(107,100,205,0.7)";
}

Sets the lightness of a color to the provided value. The lightness range can be from 0 and 1.

setLightness(lightness: number, color: string): string
Parameters
lightness (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: setLightness(0.2, '#CCCD64'),
  background: setLightness(0.75, 'rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${setLightness(0.2, '#CCCD64')};
  background: ${setLightness(0.75, 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#4d4d19";
  background: "rgba(223,224,159,0.7)";
}

Sets the saturation of a color to the provided value. The lightness range can be from 0 and 1.

setSaturation(saturation: number, color: string): string
Parameters
saturation (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: setSaturation(0.2, '#CCCD64'),
  background: setSaturation(0.75, 'rgba(204,205,100,0.7)'),
}

// styled-components usage
const div = styled.div`
  background: ${setSaturation(0.2, '#CCCD64')};
  background: ${setSaturation(0.75, 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#adad84";
  background: "rgba(228,229,76,0.7)";
}

Shades a color by mixing it with black. shade can produce hue shifts, where as darken manipulates the luminance channel and therefore doesn't produce hue shifts.

shade(percentage: number, color: string): string
Parameters
percentage (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: shade(0.25, '#00f')
}

// styled-components usage
const div = styled.div`
  background: ${shade(0.25, '#00f')};
`

// CSS in JS Output

element {
  background: "#00003f";
}

Tints a color by mixing it with white. tint can produce hue shifts, where as lighten manipulates the luminance channel and therefore doesn't produce hue shifts.

tint(percentage: number, color: string): string
Parameters
percentage (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: tint(0.25, '#00f')
}

// styled-components usage
const div = styled.div`
  background: ${tint(0.25, '#00f')};
`

// CSS in JS Output

element {
  background: "#bfbfff";
}

Decreases the opacity of a color. Its range for the amount is between 0 to 1.

transparentize(amount: number, color: string): string
Parameters
amount (number)
color (string)
Returns
string
Example
// Styles as object usage
const styles = {
  background: transparentize(0.1, '#fff');
  background: transparentize(0.2, 'hsl(0, 0%, 100%)'),
  background: transparentize(0.5, 'rgba(255, 0, 0, 0.8)'),
}

// styled-components usage
const div = styled.div`
  background: ${transparentize(0.1, '#fff')};
  background: ${transparentize(0.2, 'hsl(0, 0%, 100%)')},
  background: ${transparentize(0.5, 'rgba(255, 0, 0, 0.8)')},
`

// CSS in JS Output

element {
  background: "rgba(255,255,255,0.9)";
  background: "rgba(255,255,255,0.8)";
  background: "rgba(255,0,0,0.3)";
}

Shorthands

Shorthand for easily setting the animation property. Allows either multiple arrays with animations or a single animation spread over the arguments.

Parameters
Returns
Object
Example
// Styles as object usage
const styles = {
  ...animation(['rotate', '1s', 'ease-in-out'], ['colorchange', '2s'])
}

// styled-components usage
const div = styled.div`
  ${animation(['rotate', '1s', 'ease-in-out'], ['colorchange', '2s'])}
`

// CSS as JS Output

div {
  'animation': 'rotate 1s ease-in-out, colorchange 2s'
}
// Styles as object usage
const styles = {
  ...animation('rotate', '1s', 'ease-in-out')
}

// styled-components usage
const div = styled.div`
  ${animation('rotate', '1s', 'ease-in-out')}
`

// CSS as JS Output

div {
  'animation': 'rotate 1s ease-in-out'
}

Shorthand that accepts any number of backgroundImage values as parameters for creating a single background statement.

backgroundImages(properties: ...Array<string>): Object
Parameters
properties (...Array<string>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...backgroundImages('url("/image/background.jpg")', 'linear-gradient(red, green)')
}

// styled-components usage
const div = styled.div`
  ${backgroundImages('url("/image/background.jpg")', 'linear-gradient(red, green)')}
`

// CSS as JS Output

div {
  'backgroundImage': 'url("/image/background.jpg"), linear-gradient(red, green)'
}

Shorthand that accepts any number of background values as parameters for creating a single background statement.

backgrounds(properties: ...Array<string>): Object
Parameters
properties (...Array<string>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...backgrounds('url("/image/background.jpg")', 'linear-gradient(red, green)', 'center no-repeat')
}

// styled-components usage
const div = styled.div`
  ${backgrounds('url("/image/background.jpg")', 'linear-gradient(red, green)', 'center no-repeat')}
`

// CSS as JS Output

div {
  'background': 'url("/image/background.jpg"), linear-gradient(red, green), center no-repeat'
}

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.

borderColor(values: ...Array<string?>): Object
Parameters
values (...Array<string?>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...borderColor('red', 'green', 'blue', 'yellow')
}

// styled-components usage
const div = styled.div`
  ${borderColor('red', 'green', 'blue', 'yellow')}
`

// CSS as JS Output

div {
  'borderTopColor': 'red',
  'borderRightColor': 'green',
  'borderBottomColor': 'blue',
  'borderLeftColor': 'yellow'
}

Shorthand that accepts a value for side and a value for radius and applies the radius value to both corners of the side.

borderRadius(side: string, radius: (string | number)): Object
Parameters
side (string)
radius ((string | number))
Returns
Object
Example
// Styles as object usage
const styles = {
  ...borderRadius('top', '5px')
}

// styled-components usage
const div = styled.div`
  ${borderRadius('top', '5px')}
`

// CSS as JS Output

div {
  'borderTopRightRadius': '5px',
  'borderTopLeftRadius': '5px',
}

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.

borderStyle(values: ...Array<string?>): Object
Parameters
values (...Array<string?>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...borderStyle('solid', 'dashed', 'dotted', 'double')
}

// styled-components usage
const div = styled.div`
  ${borderStyle('solid', 'dashed', 'dotted', 'double')}
`

// CSS as JS Output

div {
  'borderTopStyle': 'solid',
  'borderRightStyle': 'dashed',
  'borderBottomStyle': 'dotted',
  'borderLeftStyle': 'double'
}

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.

borderWidth(values: ...Array<(string? | number?)>): Object
Parameters
values (...Array<(string? | number?)>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...borderWidth('12px', '24px', '36px', '48px')
}

// styled-components usage
const div = styled.div`
  ${borderWidth('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'borderTopWidth': '12px',
  'borderRightWidth': '24px',
  'borderBottomWidth': '36px',
  'borderLeftWidth': '48px'
}

Populates selectors that target all buttons. You can pass optional states to append to the selectors.

buttons(states: ...Array<InteractionState>): string
Parameters
states (...Array<InteractionState>)
Returns
string
Example
// Styles as object usage
const styles = {
  [buttons('active')]: {
    'border': 'none'
  }
}

// styled-components usage
const div = styled.div`
  > ${buttons('active')} {
    border: none;
  }
`

// CSS in JS Output

 'button:active,
 'input[type="button"]:active,
 'input[type=\"reset\"]:active,
 'input[type=\"submit\"]:active: {
  'border': 'none'
}

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.

margin(values: ...Array<(string? | number?)>): Object
Parameters
values (...Array<(string? | number?)>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...margin('12px', '24px', '36px', '48px')
}

// styled-components usage
const div = styled.div`
  ${margin('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'marginTop': '12px',
  'marginRight': '24px',
  'marginBottom': '36px',
  'marginLeft': '48px'
}

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.

padding(values: ...Array<(string? | number?)>): Object
Parameters
values (...Array<(string? | number?)>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...padding('12px', '24px', '36px', '48px')
}

// styled-components usage
const div = styled.div`
  ${padding('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'paddingTop': '12px',
  'paddingRight': '24px',
  'paddingBottom': '36px',
  'paddingLeft': '48px'
}

Shorthand accepts up to five values, including null to skip a value, and maps them to their respective directions. The first value can optionally be a position keyword.

position(positionKeyword: (string | null), values: ...Array<(string? | number?)>): Object
Parameters
positionKeyword ((string | null))
values (...Array<(string? | number?)>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...position('12px', '24px', '36px', '48px')
}

// styled-components usage
const div = styled.div`
  ${position('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'top': '12px',
  'right': '24px',
  'bottom': '36px',
  'left': '48px'
}

// Styles as object usage
const styles = {
  ...position('absolute', '12px', '24px', '36px', '48px')
}

// styled-components usage
const div = styled.div`
  ${position('absolute', '12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'position': 'absolute',
  'top': '12px',
  'right': '24px',
  'bottom': '36px',
  'left': '48px'
}

Shorthand to set the height and width properties in a single statement.

size(height: (string | number), width: (string | number)?): Object
Parameters
height ((string | number))
width ((string | number)? = height)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...size('300px', '250px')
}

// styled-components usage
const div = styled.div`
  ${size('300px', '250px')}
`

// CSS as JS Output

div {
  'height': '300px',
  'width': '250px',
}

Populates selectors that target all text inputs. You can pass optional states to append to the selectors.

textInputs(states: ...Array<InteractionState>): string
Parameters
states (...Array<InteractionState>)
Returns
string
Example
// Styles as object usage
const styles = {
  [textInputs('active')]: {
    'border': 'none'
  }
}

// styled-components usage
const div = styled.div`
  > ${textInputs('active')} {
    border: none;
  }
`

// CSS in JS Output

 'input[type="color"]:active,
 input[type="date"]:active,
 input[type="datetime"]:active,
 input[type="datetime-local"]:active,
 input[type="email"]:active,
 input[type="month"]:active,
 input[type="number"]:active,
 input[type="password"]:active,
 input[type="search"]:active,
 input[type="tel"]:active,
 input[type="text"]:active,
 input[type="time"]:active,
 input[type="url"]:active,
 input[type="week"]:active,
 input:not([type]):active,
 textarea:active': {
  'border': 'none'
}

Shorthand that accepts any number of transition values as parameters for creating a single transition statement.

transitions(properties: ...Array<string>): Object
Parameters
properties (...Array<string>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...transitions('opacity 1.0s ease-in 0s', 'width 2.0s ease-in 2s')
}

// styled-components usage
const div = styled.div`
  ${transitions('opacity 1.0s ease-in 0s', 'width 2.0s ease-in 2s')}
`

// CSS as JS Output

div {
  'transition': 'opacity 1.0s ease-in 0s, width 2.0s ease-in 2s'
}

Helpers

A helper that enables shorthand for direction based properties. It accepts a property (hyphenated or camelCased) and up to four values that map to top, right, bottom, and left, respectively. You can optionally pass an empty string to get only the directional values as properties. You can also optionally pass a null argument for a directional value to ignore it.

directionalProperty(property: string, values: ...Array<(string? | number?)>): Object
Parameters
property (string)
values (...Array<(string? | number?)>)
Returns
Object
Example
// Styles as object usage
const styles = {
  ...directionalProperty('padding', '12px', '24px', '36px', '48px')
}

// styled-components usage
const div = styled.div`
  ${directionalProperty('padding', '12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'paddingTop': '12px',
  'paddingRight': '24px',
  'paddingBottom': '36px',
  'paddingLeft': '48px'
}

Convert pixel value to ems. The default base value is 16px, but can be changed by passing a second argument to the function.

em(pxval: (string | number), base: (string | number)?)

Type: function (value: (string | number), base: (string | number)): string

Parameters
pxval ((string | number))
base ((string | number)? = '16px')
Example
// Styles as object usage
const styles = {
  'height': em('16px')
}

// styled-components usage
const div = styled.div`
  height: ${em('16px')}
`

// CSS in JS Output

element {
  'height': '1em'
}

Establish consistent measurements and spacial relationships throughout your projects by incrementing up or down a defined scale. We provide a list of commonly used scales as pre-defined variables, see below.

modularScale(steps: number, base: (number | string)?, ratio: Ratio?): string
Parameters
steps (number)
base ((number | string)? = '1em')
ratio (Ratio? = 'perfectFourth')
Returns
string
Example
// Styles as object usage
const styles = {
   // Increment two steps up the default scale
  'fontSize': modularScale(2)
}

// styled-components usage
const div = styled.div`
   // Increment two steps up the default scale
  fontSize: ${modularScale(2)}
`

// CSS in JS Output

element {
  'fontSize': '1.77689em'
}

Convert pixel value to rems. The default base value is 16px, but can be changed by passing a second argument to the function.

rem(pxval: (string | number), base: (string | number)?)

Type: function (value: (string | number), base: (string | number)): string

Parameters
pxval ((string | number))
base ((string | number)? = '16px')
Example
// Styles as object usage
const styles = {
  'height': rem('16px')
}

// styled-components usage
const div = styled.div`
  height: ${rem('16px')}
`

// CSS in JS Output

element {
  'height': '1rem'
}

Strip the unit from a given CSS value, returning just the number. (or the original value if an invalid string was passed)

stripUnit(value: string): (number | string)
Parameters
value (string)
Returns
(number | string)
Example
// Styles as object usage
const styles = {
  '--dimension': stripUnit('100px')
}

// styled-components usage
const div = styled.div`
  --dimension: ${stripUnit('100px')}
`

// CSS in JS Output

element {
  '--dimension': 100
}

Types

AnimationProperty

Type: (string | number)

FontFaceConfiguration

src/mixins/fontFace.js
FontFaceConfiguration

Type: {fontFamily: string, fontFilePath: string?, fontStretch: string?, fontStyle: string?, fontVariant: string?, fontWeight: string?, fileFormats: Array<string>?, localFonts: Array<string>?, unicodeRange: string?}

Properties
fontFamily (string)
fontFilePath (string?)
fontStretch (string?)
fontStyle (string?)
fontVariant (string?)
fontWeight (string?)
fileFormats (Array<string>?)
localFonts (Array<string>?)
unicodeRange (string?)
HslColor

Type: {hue: number, saturation: number, lightness: number}

Properties
hue (number)
saturation (number)
lightness (number)
HslaColor

Type: {hue: number, saturation: number, lightness: number, alpha: number}

Properties
hue (number)
saturation (number)
lightness (number)
alpha (number)
InteractionState

Type: (any | null | "active" | "focus" | "hover")

PointingDirection

src/mixins/triangle.js
PointingDirection

Type: ("top" | "right" | "bottom" | "left")

RadialGradientConfiguration

src/mixins/radialGradient.js
RadialGradientConfiguration

Type: {colorStops: Array<string>, extent: string?, fallback: string?, position: string?, shape: string?}

Properties
colorStops (Array<string>)
extent (string?)
fallback (string?)
position (string?)
shape (string?)
Ratio

Type: (number | "minorSecond" | "majorSecond" | "minorThird" | "majorThird" | "perfectFourth" | "augFourth" | "perfectFifth" | "minorSixth" | "goldenSection" | "majorSixth" | "minorSeventh" | "majorSeventh" | "octave" | "majorTenth" | "majorEleventh" | "majorTwelfth" | "doubleOctave")

RgbaColor

Type: {red: number, green: number, blue: number, alpha: number}

Properties
red (number)
green (number)
blue (number)
alpha (number)
RgbColor

Type: {red: number, green: number, blue: number}

Properties
red (number)
green (number)
blue (number)
TimingFunction

Type: ("easeInBack" | "easeInCirc" | "easeInCubic" | "easeInExpo" | "easeInQuad" | "easeInQuart" | "easeInQuint" | "easeInSine" | "easeOutBack" | "easeOutCubic" | "easeOutCirc" | "easeOutExpo" | "easeOutQuad" | "easeOutQuart" | "easeOutQuint" | "easeOutSine" | "easeInOutBack" | "easeInOutCirc" | "easeInOutCubic" | "easeInOutExpo" | "easeInOutQuad" | "easeInOutQuart" | "easeInOutQuint" | "easeInOutSine")

Converts a RgbColor, RgbaColor, HslColor or HslaColor object to a color string. This util is useful in case you only know on runtime which color object is used. Otherwise we recommend to rely on rgb, rgba, hsl or hsla.

toColorString(color: Object): string
Parameters
color (Object)
Returns
string
Example
// Styles as object usage
const styles = {
  background: toColorString({ red: 255, green: 205, blue: 100 }),
  background: toColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 }),
  background: toColorString({ hue: 240, saturation: 1, lightness: 0.5 }),
  background: toColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 }),
}

// styled-components usage
const div = styled.div`
  background: ${toColorString({ red: 255, green: 205, blue: 100 })};
  background: ${toColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 })};
  background: ${toColorString({ hue: 240, saturation: 1, lightness: 0.5 })};
  background: ${toColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 })};
`

// CSS in JS Output
element {
  background: "#ffcd64";
  background: "rgba(255,205,100,0.72)";
  background: "#00f";
  background: "rgba(179,25,25,0.72)";
}
ModularScaleRatio

Type: (number | "minorSecond" | "majorSecond" | "minorThird" | "majorThird" | "perfectFourth" | "augFourth" | "perfectFifth" | "minorSixth" | "goldenSection" | "majorSixth" | "minorSeventh" | "majorSeventh" | "octave" | "majorTenth" | "majorEleventh" | "majorTwelfth" | "doubleOctave")