###

Need help reading this?

## Installation

`npm install --save polished`

## Usage

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

## Mixins

### between

Returns a CSS calc formula for linear interpolation of a property between two values. Accepts optional minScreen (defaults to '320px') and maxScreen (defaults to '1200px').

between(fromSize: (string | number), toSize: (string | number), minScreen: string, maxScreen: string): string

Extends

Parameters
fromSize `((string | number))`
toSize `((string | number))`
minScreen `(string = `'320px'`)`
maxScreen `(string = `'1200px'`)`
Properties
Returns
`string`
Throws

Example

    // Styles as object usage
    const styles = {
      fontSize: between('20px', '100px', '400px', '1000px'),
      fontSize: between('20px', '100px')
    }

    // styled-components usage
    const div = styled.div`
      fontSize: ${between('20px', '100px', '400px', '1000px')};
      fontSize: ${between('20px', '100px')}
    `

    // CSS as JS Output

    h1: {
      'fontSize': 'calc(-33.33333333333334px + 13.333333333333334vw)',
      'fontSize': 'calc(-9.090909090909093px + 9.090909090909092vw)'
    }

### clearFix

CSS to contain a float (credit to CSSMojo).

clearFix(parent: string): Styles

Extends

Parameters
parent `(string = `'&'`)`
Properties
Returns
`Styles`
Throws

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

### cover

CSS to fully cover an area. Can optionally be passed an offset to act as a "padding".

cover(offset: (number | string)): Styles

Extends

Parameters
offset `((number | string) = `0`)`
Properties
Returns
`Styles`
Throws

Example

    // Styles as object usage
    const styles = {
      ...cover()
    }

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

    // CSS as JS Output

    div: {
      'position': 'absolute',
      'top': '0',
      'right: '0',
      'bottom': '0',
      'left: '0'
    }

### ellipsis

CSS to represent truncated text with an ellipsis. You can optionally pass a max-width and number of lines before truncating.

ellipsis(width: (string? | number?)?, lines: number): Styles

Extends

Parameters
width `((string? | number?)?)`
lines `(number = `1`)`
Properties
Returns
`Styles`
Throws

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

### fluidRange

Returns a set of media queries that resizes a property (or set of properties) between a provided fromSize and toSize. Accepts optional minScreen (defaults to '320px') and maxScreen (defaults to '1200px') to constrain the interpolation.

fluidRange(cssProp: (Array<FluidRangeConfiguration> | FluidRangeConfiguration), minScreen: string, maxScreen: string): Styles

Extends

Parameters
cssProp `((Array<FluidRangeConfiguration> | FluidRangeConfiguration))`
minScreen `(string = `'320px'`)`
maxScreen `(string = `'1200px'`)`
Properties
Returns
`Styles`
Throws

Example

    // Styles as object usage
    const styles = {
      ...fluidRange(
       {
           prop: 'padding',
           fromSize: '20px',
           toSize: '100px',
         },
         '400px',
         '1000px',
       )
    }

    // styled-components usage
    const div = styled.div`
      ${fluidRange(
         {
           prop: 'padding',
           fromSize: '20px',
           toSize: '100px',
         },
         '400px',
         '1000px',
       )}
    `

    // CSS as JS Output

    div: {
      "@media (min-width: 1000px)": Object {
        "padding": "100px",
      },
      "@media (min-width: 400px)": Object {
        "padding": "calc(-33.33333333333334px + 13.333333333333334vw)",
      },
      "padding": "20px",
    }

### fontFace

CSS for a @font-face declaration. Defaults to check for local copies of the font on the user's machine. You can disable this by passing `null` to localFonts.

fontFace($0: FontFaceConfiguration): Styles

Extends

Parameters
$0 `(FontFaceConfiguration)`

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.formatHint `any` (default `false`) |
$0.localFonts `any` (default `[fontFamily]`) |
$0.unicodeRange `any` |
$0.fontDisplay `any` |
$0.fontVariationSettings `any` |
$0.fontFeatureSettings `any` |

Properties
Returns
`Styles`
Throws

Example

    // Styles as object basic usage
    const styles = {
       ...fontFace({
         'fontFamily': 'Sans-Pro',
         'fontFilePath': 'path/to/file'
       })
    }

    // styled-components basic usage
    const GlobalStyle = createGlobalStyle`${
      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")',
    }

### hideText

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

hideText(): Styles

Extends

Parameters
Properties
Returns
`Styles`
Throws

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

### hideVisually

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

hideVisually(): Styles

Extends

Parameters
Properties
Returns
`Styles`
Throws

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)',
      'height': '1px',
      'margin': '-1px',
      'overflow': 'hidden',
      'padding': '0',
      'position': 'absolute',
      'whiteSpace': 'nowrap',
      'width': '1px',
    }

### hiDPI

Generates a media query to target HiDPI devices.

hiDPI(ratio: number): string

Extends

Parameters
ratio `(number = `1.3`)`
Properties
Returns
`string`
Throws

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

### linearGradient

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

linearGradient($0: LinearGradientConfiguration): Styles

Extends

Parameters
$0 `(LinearGradientConfiguration)`

Name | Description
--- | ---
$0.colorStops `any` |
$0.fallback `any` |
$0.toDirection `any` (default `''`) |

Properties
Returns
`Styles`
Throws

Example

    // Styles as object usage
    const styles = {
      ...linearGradient({
    colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
    toDirection: 'to top right',
    fallback: '#FFF',
    })
    }

    // styled-components usage
    const div = styled.div`
      ${linearGradient({
    colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
    toDirection: 'to top right',
    fallback: '#FFF',
    })}
    `

    // CSS as JS Output

    div: {
      'backgroundColor': '#FFF',
      'backgroundImage': 'linear-gradient(to top right, #00FFFF 0%, rgba(0, 0, 255, 0) 50%, #0000FF 95%)',
    }

### normalize

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

normalize(): Array<Styles>

Extends

Parameters
Properties
Returns
`Array<Styles>`
Throws

Example

    // Styles as object usage
    const styles = {
       ...normalize(),
    }

    // styled-components usage
    const GlobalStyle = createGlobalStyle`${normalize()}`

    // CSS as JS Output

    html {
      lineHeight: 1.15,
      textSizeAdjust: 100%,
    } ...

### radialGradient

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: RadialGradientConfiguration): Styles

Extends

Parameters
$0 `(RadialGradientConfiguration)`

Name | Description
--- | ---
$0.colorStops `any` |
$0.extent `any` (default `''`) |
$0.fallback `any` |
$0.position `any` (default `''`) |
$0.shape `any` (default `''`) |

Properties
Returns
`Styles`
Throws

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

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): Styles

Extends

Parameters
filename `(string)`
backgroundSize `(string?)`
extension `(string = `'png'`)`
retinaFilename `(string?)`
retinaSuffix `(string = `'_2x'`)`
Properties
Returns
`Styles`
Throws

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

### timingFunctions

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

timingFunctions(timingFunction: TimingFunction): string

Extends

Parameters
timingFunction `(TimingFunction)`
Properties
Returns
`string`
Throws

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

CSS to represent triangle with any pointing direction with an optional background color.

triangle($0: TriangleConfiguration): Styles

Extends

Parameters
$0 `(TriangleConfiguration)`

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

Properties
Returns
`Styles`
Throws

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 transparent transparent red',
     'borderStyle': 'solid',
     'borderWidth': '50px 0 50px 100px',
     'height': '0',
     'width': '0',
    }

### wordWrap

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

wordWrap(wrap: string): Styles

Extends

Parameters
wrap `(string = `'break-word'`)`
Properties
Returns
`Styles`
Throws

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

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 around the color wheel, always producing a positive hue value.

adjustHue(degree: (number | string), color: string): string

Extends

Parameters
degree `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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

complement(color: string): string

Extends

Parameters
color `(string)`
Properties
Returns
`string`
Throws

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

Returns a string value for the darkened color.

darken(amount: (number | string), color: string): string

Extends

Parameters
amount `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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 | string), color: string): string

Extends

Parameters
amount `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

### getContrast

Returns the contrast ratio between two colors based on W3's recommended equation for calculating contrast.

getContrast(color1: string, color2: string): number

Extends

Parameters
color1 `(string)`
color2 `(string)`
Properties
Returns
`number`
Throws

Example

    const contrastRatio = getContrast('#444', '#fff');

### getLuminance

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

getLuminance(color: string): number

Extends

Parameters
color `(string)`
Properties
Returns
`number`
Throws

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

### grayscale

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

grayscale(color: string): string

Extends

Parameters
color `(string)`
Properties
Returns
`string`
Throws

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

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

Extends

Parameters
value `((HslColor | number))`
saturation `(number?)`
lightness `(number?)`
Properties
Returns
`string`
Throws

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

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

Extends

Parameters
value `((HslaColor | number))`
saturation `(number?)`
lightness `(number?)`
alpha `(number?)`
Properties
Returns
`string`
Throws

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

### hslToColorString

Converts a 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 `hsl` or `hsla`.

hslToColorString(color: (HslColor | HslaColor | number)): string

Extends

Parameters
color `((HslColor | HslaColor | number))`
Properties
Returns
`string`
Throws

Example

    // Styles as object usage
    const styles = {
      background: hslToColorString({ hue: 240, saturation: 1, lightness: 0.5 }),
      background: hslToColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 }),
    }

    // styled-components usage
    const div = styled.div`
      background: ${hslToColorString({ hue: 240, saturation: 1, lightness: 0.5 })};
      background: ${hslToColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 })};
    `

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

### invert

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

invert(color: string): string

Extends

Parameters
color `(string)`
Properties
Returns
`string`
Throws

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

Returns a string value for the lightened color.

lighten(amount: (number | string), color: string): string

Extends

Parameters
amount `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

### meetsContrastGuidelines

Determines which contrast guidelines have been met for two colors. Based on the contrast calculations recommended by W3.

meetsContrastGuidelines(color1: string, color2: string): ContrastScores

Extends

Parameters
color1 `(string)`
color2 `(string)`
Properties
Returns
`ContrastScores`
Throws

Example

    const scores = meetsContrastGuidelines('#444', '#fff');

### mix

Mixes the two provided colors together by calculating the average of each of the RGB components weighted to the first color by the provided weight.

mix(weight: (number | string), color: string, otherColor: string): string

Extends

Parameters
weight `((number | string))`
color `(string)`
otherColor `(string)`
Properties
Returns
`string`
Throws

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

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

opacify(amount: (number | string), color: string): string

Extends

Parameters
amount `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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)

Extends

Parameters
color `(string)`
Properties
Returns
`(HslColor | HslaColor)`
Throws

Example

    // Assigns `{ hue: 0, saturation: 1, lightness: 0.5 }` to color1
    const color1 = parseToHsl('rgb(255, 0, 0)');
    // Assigns `{ hue: 128, saturation: 1, lightness: 0.5, alpha: 0.75 }` to color2
    const color2 = parseToHsl('hsla(128, 100%, 50%, 0.75)');

### parseToRgb

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)

Extends

Parameters
color `(string)`
Properties
Returns
`(RgbColor | RgbaColor)`
Throws

Example

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

### readableColor

Returns black or white (or optional passed colors) for best contrast depending on the luminosity of the given color. When passing custom return colors, strict mode ensures that the return color always meets or exceeds WCAG level AA or greater. If this test fails, the default return color (black or white) is returned in place of the custom return color. You can optionally turn off strict mode.

Follows W3C specs for readability.

readableColor(color: string, returnIfLightColor: string, returnIfDarkColor: string, strict: boolean): string

Extends

Parameters
color `(string)`
returnIfLightColor `(string = `defaultReturnIfLightColor`)`
returnIfDarkColor `(string = `defaultReturnIfDarkColor`)`
strict `(boolean = `true`)`
Properties
Returns
`string`
Throws

Example

    // Styles as object usage
    const styles = {
      color: readableColor('#000'),
      color: readableColor('black', '#001', '#ff8'),
      color: readableColor('white', '#001', '#ff8'),
      color: readableColor('red', '#333', '#ddd', true)
    }

    // styled-components usage
    const div = styled.div`
      color: ${readableColor('#000')};
      color: ${readableColor('black', '#001', '#ff8')};
      color: ${readableColor('white', '#001', '#ff8')};
      color: ${readableColor('red', '#333', '#ddd', true)};
    `

    // CSS in JS Output
    element {
      color: "#fff";
      color: "#ff8";
      color: "#001";
      color: "#000";
    }

### rgb

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

Extends

Parameters
value `((RgbColor | number))`
green `(number?)`
blue `(number?)`
Properties
Returns
`string`
Throws

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

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

Extends

Parameters
firstValue `((RgbaColor | number | string))`
secondValue `(number?)`
thirdValue `(number?)`
fourthValue `(number?)`
Properties
Returns
`string`
Throws

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

### rgbToColorString

Converts a RgbColor or RgbaColor 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` or `rgba`.

rgbToColorString(color: (RgbColor | RgbaColor)): string

Extends

Parameters
color `((RgbColor | RgbaColor))`
Properties
Returns
`string`
Throws

Example

    // Styles as object usage
    const styles = {
      background: rgbToColorString({ red: 255, green: 205, blue: 100 }),
      background: rgbToColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 }),
    }

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

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

### saturate

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 | string), color: string): string

Extends

Parameters
amount `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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

setHue(hue: (number | string), color: string): string

Extends

Parameters
hue `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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

setLightness(lightness: (number | string), color: string): string

Extends

Parameters
lightness `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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

setSaturation(saturation: (number | string), color: string): string

Extends

Parameters
saturation `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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 | string), color: string): string

Extends

Parameters
percentage `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

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 | string), color: string): string

Extends

Parameters
percentage `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

### toColorString

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

Extends

Parameters
color `(Object)`
Properties
Returns
`string`
Throws

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

### transparentize

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

transparentize(amount: (number | string), color: string): string

Extends

Parameters
amount `((number | string))`
color `(string)`
Properties
Returns
`string`
Throws

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

## Math

Helper for doing math with CSS Units. Accepts a formula as a string. All values in the formula must have the same unit (or be unitless). Supports complex formulas utliziing addition, subtraction, multiplication, division, square root, powers, factorial, min, max, as well as parentheses for order of operation.

In cases where you need to do calculations with mixed units where one unit is a relative length unit, you will want to use CSS Calc.

warning While we've done everything possible to ensure math safely evalutes formulas expressed as strings, you should always use extreme caution when passing `math` user provided values.

math(formula: string, additionalSymbols: Object?): string

Extends

Parameters
formula `(string)`
additionalSymbols `(Object?)`
Properties
Returns
`string`
Throws

Example

    // Styles as object usage
    const styles = {
      fontSize: math('12rem + 8rem'),
      fontSize: math('(12px + 2px) * 3'),
      fontSize: math('3px^2 + sqrt(4)'),
    }

    // styled-components usage
    const div = styled.div`
      fontSize: ${math('12rem + 8rem')};
      fontSize: ${math('(12px + 2px) * 3')};
      fontSize: ${math('3px^2 + sqrt(4)')};
    `

    // CSS as JS Output

    div: {
      fontSize: '20rem',
      fontSize: '42px',
      fontSize: '11px',
    }

## Shorthands

### animation

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<(string | number)> | string | number)>): Styles

Extends

Parameters
args `(...Array<(Array<(string | number)> | string | number)>)`
Properties
Returns
`Styles`
Throws

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

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

backgroundImages(properties: ...Array<string>): Styles

Extends

Parameters
properties `(...Array<string>)`
Properties
Returns
`Styles`
Throws

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

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

backgrounds(properties: ...Array<string>): Styles

Extends

Parameters
properties `(...Array<string>)`
Properties
Returns
`Styles`
Throws

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

### border

Shorthand for the border property that splits out individual properties for use with tools like Fela and Styletron. A side keyword can optionally be passed to target only one side's border properties.

border(sideKeyword: (SideKeyword | string | number), values: ...Array<(string | number)>): Styles

Extends

Parameters
sideKeyword `((SideKeyword | string | number))`
values `(...Array<(string | number)>)`
Properties
Returns
`Styles`
Throws

Example

    // Styles as object usage
    const styles = {
      ...border('1px', 'solid', 'red')
    }

    // styled-components usage
    const div = styled.div`
      ${border('1px', 'solid', 'red')}
    `

    // CSS as JS Output

    div {
      'borderColor': 'red',
      'borderStyle': 'solid',
      'borderWidth': `1px`,
    }

    // Styles as object usage
    const styles = {
      ...border('top', '1px', 'solid', 'red')
    }

    // styled-components usage
    const div = styled.div`
      ${border('top', '1px', 'solid', 'red')}
    `

    // CSS as JS Output

    div {
      'borderTopColor': 'red',
      'borderTopStyle': 'solid',
      'borderTopWidth': `1px`,
    }

### borderColor

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

borderColor(values: ...Array<string?>): Styles

Extends

Parameters
values `(...Array<string?>)`
Properties
Returns
`Styles`
Throws

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

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)): Styles

Extends

Parameters
side `(string)`
radius `((string | number))`
Properties
Returns
`Styles`
Throws

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

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

borderStyle(values: ...Array<string?>): Styles

Extends

Parameters
values `(...Array<string?>)`
Properties
Returns
`Styles`
Throws

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

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?)>): Styles

Extends

Parameters
values `(...Array<(string? | number?)>)`
Properties
Returns
`Styles`
Throws

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

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

buttons(states: ...Array<InteractionState>): string

Extends

Parameters
states `(...Array<InteractionState>)`
Properties
Returns
`string`
Throws

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

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?)>): Styles

Extends

Parameters
values `(...Array<(string? | number?)>)`
Properties
Returns
`Styles`
Throws

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

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?)>): Styles

Extends

Parameters
values `(...Array<(string? | number?)>)`
Properties
Returns
`Styles`
Throws

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

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(firstValue: (string | number | null)?, values: ...Array<(string? | number?)>): Styles

Extends

Parameters
firstValue `((string | number | null)?)`
values `(...Array<(string? | number?)>)`
Properties
Returns
`Styles`
Throws

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

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

size(height: (string | number), width: (string | number)): Styles

Extends

Parameters
height `((string | number))`
width `((string | number) = `height`)`
Properties
Returns
`Styles`
Throws

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

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

textInputs(states: ...Array<InteractionState>): string

Extends

Parameters
states `(...Array<InteractionState>)`
Properties
Returns
`string`
Throws

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

Accepts any number of transition values as parameters for creating a single transition statement. You may also pass an array of properties as the first parameter that you would like to apply the same transition values to (second parameter).

transitions(properties: ...Array<(string | Array<string>)>): Styles

Extends

Parameters
properties `(...Array<(string | Array<string>)>)`
Properties
Returns
`Styles`
Throws

Example

    // Styles as object usage
    const styles = {
      ...transitions('opacity 1.0s ease-in 0s', 'width 2.0s ease-in 2s'),
      ...transitions(['color', 'background-color'], '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')};
      ${transitions(['color', 'background-color'], '2.0s ease-in 2s'),};
    `

    // CSS as JS Output

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

## Helpers

### cssVar

Fetches the value of a passed CSS Variable in the :root scope, or otherwise returns a defaultValue if provided.

cssVar(cssVariable: string, defaultValue: (string | number)?): (string | number)

Extends

Parameters
cssVariable `(string)`
defaultValue `((string | number)?)`
Properties
Returns
`(string | number)`
Throws

Example

    // Styles as object usage
    const styles = {
      'background': cssVar('--background-color'),
    }

    // styled-components usage
    const div = styled.div`
      background: ${cssVar('--background-color')};
    `

    // CSS in JS Output

    element {
      'background': 'red'
    }

### directionalProperty

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?)>): Styles

Extends

Parameters
property `(string)`
values `(...Array<(string? | number?)>)`
Properties
Returns
`Styles`
Throws

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

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

Extends

Parameters
pxval `((string | number))`
base `((string | number) = `'16px'`)`
Properties
Throws

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

### getValueAndUnit

Returns a given CSS value and its unit as elements of an array.

getValueAndUnit(value: (string | number)): any

Extends

Parameters
value `((string | number))`
Properties
Returns
`any`
Throws

Example

    // Styles as object usage
    const styles = {
      '--dimension': getValueAndUnit('100px')[0],
      '--unit': getValueAndUnit('100px')[1],
    }

    // styled-components usage
    const div = styled.div`
      --dimension: ${getValueAndUnit('100px')[0]};
      --unit: ${getValueAndUnit('100px')[1]};
    `

    // CSS in JS Output

    element {
      '--dimension': 100,
      '--unit': 'px',
    }

### important

Helper for targeting rules in a style block generated by polished modules that need !important-level specificity. Can optionally specify a rule (or rules) to target specific rules.

important(styleBlock: Styles, rules: (Array<string> | string)?): Styles

Extends

Parameters
styleBlock `(Styles)`
rules `((Array<string> | string)?)`
Properties
Returns
`Styles`
Throws

Example

    // Styles as object usage
    const styles = {
      ...important(cover())
    }

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

    // CSS as JS Output

    div: {
      'position': 'absolute !important',
      'top': '0 !important',
      'right: '0 !important',
      'bottom': '0 !important',
      'left: '0 !important'
    }

### modularScale

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

modularScale(steps: number, base: (number | string), ratio: ModularScaleRatio): string

Extends

Parameters
steps `(number)`
base `((number | string) = `'1em'`)`
ratio `(ModularScaleRatio = `1.333`)`
Properties
Returns
`string`
Throws

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

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

Extends

Parameters
pxval `((string | number))`
base `((string | number) = `'16px'`)`
Properties
Throws

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

### remToPx

Convert rem values to px. By default, the base value is pulled from the font-size property on the root element (if it is set in % or px). It defaults to 16px if not found on the root. You can also override the base value by providing your own base in % or px.

remToPx(value: (string | number), base: (string | number)?): string

Extends

Parameters
value `((string | number))`
base `((string | number)?)`
Properties
Returns
`string`
Throws

Example

    // Styles as object usage
    const styles = {
      'height': remToPx('1.6rem')
      'height': remToPx('1.6rem', '10px')
    }

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

    // CSS in JS Output

    element {
      'height': '25.6px',
      'height': '16px',
    }

### stripUnit

Returns a given CSS value minus its unit of measure.

stripUnit(value: (string | number)): (string | number)

Extends

Parameters
value `((string | number))`
Properties
Returns
`(string | number)`
Throws

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
    }

## Easings

### easeIn

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

easeIn(functionName: string): TimingFunction

Extends

Parameters
functionName `(string)`
Properties
Returns
`TimingFunction`
Throws

Example

    // Styles as object usage
    const styles = {
      'transitionTimingFunction': easeIn('quad')
    }

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

    // CSS as JS Output

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

### easeInOut

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

easeInOut(functionName: string): TimingFunction

Extends

Parameters
functionName `(string)`
Properties
Returns
`TimingFunction`
Throws

Example

    // Styles as object usage
    const styles = {
      'transitionTimingFunction': easeInOut('quad')
    }

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

    // CSS as JS Output

    'div': {
      'transitionTimingFunction': 'cubic-bezier(0.455,  0.030, 0.515, 0.955)',
    }

### easeOut

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

easeOut(functionName: string): TimingFunction

Extends

Parameters
functionName `(string)`
Properties
Returns
`TimingFunction`
Throws

Example

    // Styles as object usage
    const styles = {
      'transitionTimingFunction': easeOut('quad')
    }

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

    // CSS as JS Output

    'div': {
      'transitionTimingFunction': 'cubic-bezier(0.250,  0.460, 0.450, 0.940)',
    }

## Types

### FluidRangeConfiguration

FluidRangeConfiguration

Type: {prop: string, fromSize: (string | number), toSize: (string | number)}

Extends

Parameters
Properties
prop `(string)`
fromSize `(string)`
toSize `(string)`
Throws

Example

### FontFaceConfiguration

FontFaceConfiguration

Type: {fontFamily: string, fontFilePath: string?, fontStretch: string?, fontStyle: string?, fontVariant: string?, fontWeight: string?, fileFormats: Array<string>?, formatHint: boolean?, localFonts: (Array<string> | null)?, unicodeRange: string?, fontDisplay: string?, fontVariationSettings: string?, fontFeatureSettings: string?}

Extends

Parameters
Properties
fontFamily `(string)`
fontFilePath `(string?)`
fontStretch `(string?)`
fontStyle `(string?)`
fontVariant `(string?)`
fontWeight `(string?)`
fileFormats `(Array<string>?)`
formatHint `(boolean?)`
localFonts `((Array<string>? | null))`
unicodeRange `(string?)`
fontDisplay `(string?)`
fontVariationSettings `(string?)`
fontFeatureSettings `(string?)`
Throws

Example

### HslColor

HslColor

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

Extends

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

Example

### HslaColor

HslaColor

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

Extends

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

Example

### InteractionState

InteractionState

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

Extends

Parameters
Properties
Throws

Example

### ModularScaleRatio

ModularScaleRatio

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

Extends

Parameters
Properties
Throws

Example

### RadialGradientConfiguration

RadialGradientConfiguration

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

Extends

Parameters
Properties
colorStops `(Array<string>)`
extent `(string?)`
fallback `(string?)`
position `(string?)`
shape `(string?)`
Throws

Example

### RgbaColor

RgbaColor

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

Extends

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

Example

### RgbColor

RgbColor

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

Extends

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

Example

### SideKeyword

SideKeyword

Type: (`"top"` | `"topRight"` | `"right"` | `"bottomRight"` | `"bottom"` | `"bottomLeft"` | `"left"` | `"topLeft"`)

Extends

Parameters
Properties
Throws

Example

### Styles

Styles

Type: {}

Extends

Parameters
Properties
ruleOrSelector `((string | number | Styles)?)`
Throws

Example

### TriangleConfiguration

TriangleConfiguration

Type: {backgroundColor: string?, foregroundColor: string, height: (number | string), width: (number | string), pointingDirection: SideKeyword}

Extends

Parameters
Properties
backgroundColor `(number)`
foregroundColor `(number)`
height `(number)`
height `(number)`
height `(number)`
width `((number | string))`
pointingDirection `(SideKeyword)`
Throws

Example

### ContrastScores

ContrastScores

Type: {AA: boolean, AALarge: boolean, AAA: boolean, AAALarge: boolean}

Extends

Parameters
Properties
AA `(boolean)`
AALarge `(boolean)`
AAA `(boolean)`
AAALarge `(boolean)`
Throws

Example

### LinearGradientConfiguration

LinearGradientConfiguration

Type: {colorStops: Array<string>, toDirection: string?, fallback: string?}

Extends

Parameters
Properties
colorStops `(Array<string>)`
toDirection `(string?)`
fallback `(string?)`
Throws

Example

### TimingFunction

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"`)

Extends

Parameters
Properties
Throws

Example