###

``
Need help reading this?

## Installation

`npm install --save polished`

## Usage

`import { lighten, modularScale } from 'polished'`

## Mixins

### clearFix

src/mixins/clearFix.js

CSS to contain a float (credit to CSSMojo).

clearFix(parent: string?)
Parameters
parent `(string? = `'&'`)`
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'
    }

### ellipsis

src/mixins/ellipsis.js

CSS to represent truncated text with an ellipsis.

ellipsis(width: string?)
Parameters
width `(string? = `'100%'`)`
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'
    }

### fontFace

src/mixins/fontFace.js

CSS for a @font-face declaration.

fontFace($0: 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` |

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")',
    }

### hiDPI

src/mixins/hiDPI.js

Generates a media query to target HiDPI devices.

hiDPI(ratio: number?)
Parameters
ratio `(number? = `1.3`)`
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',
    }

### hideText

src/mixins/hideText.js

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

hideText()
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',
    }

### normalize

src/mixins/normalize.js

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

normalize(excludeOpinionated: boolean)
Parameters
excludeOpinionated `(boolean)`
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%,
    } ...

### placeholder

src/mixins/placeholder.js

CSS to style the selection psuedo-element.

placeholder(styles: Object, parent: string?)
Parameters
styles `(Object)`
parent `(string? = `'&'`)`
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',
      },
    },

### radialGradient

src/mixins/radialGradient.js

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)
Parameters
$0 `(Object)`

Name | Description
--- | ---
$0.colorStops `any` |
$0.extent `any` |
$0.fallback `any` |
$0.position `any` |
$0.shape `any` |

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%)',
    }

### retinaImage

src/mixins/retinaImage.js

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?)
Parameters
filename `(string)`
backgroundSize `(string)`
extension `(string? = `'png'`)`
retinaFilename `(string)`
retinaSuffix `(string? = `'_2x'`)`
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)',
      }
    }

### selection

src/mixins/selection.js

CSS to style the selection psuedo-element.

selection(styles: Object, parent: string?)
Parameters
styles `(Object)`
parent `(string? = `''`)`
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',
      }
    }

### timingFunctions

src/mixins/timingFunctions.js

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

timingFunctions(timingFunction: TimingFunction)
Parameters
timingFunction `(TimingFunction)`
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)',
    }

### triangle

src/mixins/triangle.js

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)
Parameters
$0 `(Object)`

Name | Description
--- | ---
$0.pointingDirection `any` |
$0.height `any` |
$0.width `any` |
$0.foregroundColor `any` |
$0.backgroundColor `any` (default `'transparent'`) |

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',
    }

### wordWrap

src/mixins/wordWrap.js

Provides an easy way to change the `wordWrap` property.

wordWrap(wrap: string?)
Parameters
wrap `(string? = `'break-word'`)`
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

### adjustHue

src/color/adjustHue.js

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)";
    }

### complement

src/color/complement.js

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)";
    }

### darken

src/color/darken.js

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)";
    }

### desaturate

src/color/desaturate.js

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)";
    }

### grayscale

src/color/grayscale.js

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)";
    }

### hsl

src/color/hsl.js

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";
    }

### hsla

src/color/hsla.js

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";
    }

### invert

src/color/invert.js

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)";
    }

### lighten

src/color/lighten.js

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)";
    }

### mix

src/color/mix.js

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)";
    }

### opacify

src/color/opacify.js

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

opacify(amount: number, color: string)
Parameters
amount `(number)`
color `(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)";
    }

### parseToHsl

src/color/parseToHsl.js

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)';

### parseToRgb

src/color/parseToRgb.js

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)';

### readableColor

src/color/readableColor.js

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";
    }

### rgb

src/color/rgb.js

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";
    }

### rgba

src/color/rgba.js

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)";
    }

### saturate

src/color/saturate.js

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)";
    }

### setHue

src/color/setHue.js

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)";
    }

### setLightness

src/color/setLightness.js

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)";
    }

### setSaturation

src/color/setSaturation.js

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)";
    }

### shade

src/color/shade.js

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)
Parameters
percentage `(number)`
color `(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";
    }

### tint

src/color/tint.js

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)
Parameters
percentage `(number)`
color `(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";
    }

### transparentize

src/color/transparentize.js

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

transparentize(amount: number, color: string)
Parameters
amount `(number)`
color `(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

### animation

src/shorthands/animation.js

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

animation(args: ...Array<(Array<AnimationProperty> | AnimationProperty)>)
Parameters
args `(...Array<(Array<AnimationProperty> | AnimationProperty)>)`
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'
    }

### backgroundImages

src/shorthands/backgroundImages.js

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

backgroundImages(properties: ...Array<string>)
Parameters
properties `(...Array<string>)`
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)'
    }

### backgrounds

src/shorthands/backgrounds.js

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

backgrounds(properties: ...Array<string>)
Parameters
properties `(...Array<string>)`
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'
    }

### borderColor

src/shorthands/borderColor.js

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

borderColor(values: ...Array<string?>)
Parameters
values `(...Array<string?>)`
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'
    }

### borderRadius

src/shorthands/borderRadius.js

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)
Parameters
side `(string)`
radius `(string)`
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',
    }

### borderStyle

src/shorthands/borderStyle.js

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

borderStyle(values: ...Array<string?>)
Parameters
values `(...Array<string?>)`
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'
    }

### borderWidth

src/shorthands/borderWidth.js

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

borderWidth(values: ...Array<string?>)
Parameters
values `(...Array<string?>)`
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'
    }

### buttons

src/shorthands/buttons.js

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

buttons(states: ...Array<ButtonState>)
Parameters
states `(...Array<ButtonState>)`
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'
    }

### margin

src/shorthands/margin.js

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

margin(values: ...Array<string?>)
Parameters
values `(...Array<string?>)`
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'
    }

### padding

src/shorthands/padding.js

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

padding(values: ...Array<string?>)
Parameters
values `(...Array<string?>)`
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'
    }

### position

src/shorthands/position.js

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?>)
Parameters
positionKeyword `((string | null))`
values `(...Array<string?>)`
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'
    }

### size

src/shorthands/size.js

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

size(height: string, width: string?)
Parameters
height `(string)`
width `(string? = `height`)`
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',
    }

### textInputs

src/shorthands/textInputs.js

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

textInputs(states: ...Array<InputState>)
Parameters
states `(...Array<InputState>)`
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'
    }

### transitions

src/shorthands/transitions.js

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

transitions(properties: ...Array<string>)
Parameters
properties `(...Array<string>)`
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

### directionalProperty

src/helpers/directionalProperty.js

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?>)
Parameters
property `(string)`
values `(...Array<string?>)`
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'
    }

### em

src/helpers/em.js

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)?)
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'
    }

### modularScale

src/helpers/modularScale.js

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?)
Parameters
steps `(number)`
base `((number | string)? = `'1em'`)`
ratio `(Ratio? = `'perfectFourth'`)`
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'
    }

### rem

src/helpers/rem.js

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)?)
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'
    }

### stripUnit

src/helpers/stripUnit.js

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

src/shorthands/animation.js
AnimationProperty

Type: (string | number)

### ButtonState

src/shorthands/buttons.js
ButtonState

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

### 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

src/types/color.js
HslColor

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

Properties
hue `(number)`
saturation `(number)`
lightness `(number)`

### HslaColor

src/types/color.js
HslaColor

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

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

### InputState

src/shorthands/textInputs.js
InputState

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

src/helpers/modularScale.js
Ratio

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

### RgbaColor

src/types/color.js
RgbaColor

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

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

### RgbColor

src/types/color.js
RgbColor

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

Properties
red `(number)`
green `(number)`
blue `(number)`

### TimingFunction

src/mixins/timingFunctions.js
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"`)

### toColorString

src/color/toColorString.js

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: (RgbColor | RgbaColor | HslColor | HslaColor)): string
Parameters
color `((RgbColor | RgbaColor | HslColor | HslaColor))`
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)";
    }