@siteone/system-toolset
v1.0.0
Published
Useful functions and mixins to supercharge work with @siteone/system-* libraries
Downloads
130
Keywords
Readme
@siteone/system-toolset
Useful functions and mixins to supercharge work with @siteone/system-* libraries
Table of Contents
Install
This project uses node and npm.
$ npm install @siteone/system-toolset
$ # OR
$ yarn add @siteone/system-toolset
Usage
Use within theme or application itself. Should be used as stand-alone imports via destructuring. Like this:
import { topShadow, bottomShadow } from '@siteone/system-toolset'
Don't be afraid of bundle size increase as library is tree-shakable if bundled properly.
API
function 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 along the color wheel.
Parameters
Examples
// Styles as object usage
const styles = {
background: adjustHue(180, '#448'),
background: adjustHue('180', 'rgba(101,100,205,0.7)'),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${adjustHue(180, '#448')};
background: ${adjustHue('180', 'rgba(101,100,205,0.7)')};
`
// CSS in JS Output
element {
background: "#888844";
background: "rgba(136,136,68,0.7)";
}
Returns string
function complement
Returns the complement of the provided color. This is identical to adjustHue(180, color).
Parameters
color
string
Examples
// Styles as object usage
const styles = {
background: complement('#448'),
background: complement('rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${complement('#448')};
background: ${complement('rgba(204,205,100,0.7)')};
`
// CSS in JS Output
element {
background: "#884";
background: "rgba(153,153,153,0.7)";
}
Returns string
function darken
Returns a string value for the darkened color.
Parameters
Examples
// Styles as object usage
const styles = {
background: darken(0.2, '#FFCD64'),
background: darken('0.2', 'rgba(255,205,100,0.7)'),
}
// syled (CSS in JS) 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)";
}
Returns string
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
background: desaturate(0.2, '#CCCD64'),
background: desaturate('0.2', 'rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${desaturate(0.2, '#CCCD64')};
background: ${desaturate('0.2', 'rgba(204,205,100,0.7)')};
`
// CSS in JS Output
element {
background: "#b8b979";
background: "rgba(184,185,121,0.7)";
}
Returns string
function getLuminance
Returns a number (float) representing the luminance of a color.
Parameters
color
string
Examples
// 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)',
}
// syled (CSS in JS) 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)";
}
Returns number
function grayscale
Converts the color to a grayscale, by reducing its saturation to 0.
Parameters
color
string
Examples
// Styles as object usage
const styles = {
background: grayscale('#CCCD64'),
background: grayscale('rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${grayscale('#CCCD64')};
background: ${grayscale('rgba(204,205,100,0.7)')};
`
// CSS in JS Output
element {
background: "#999";
background: "rgba(153,153,153,0.7)";
}
Returns string
function hsl
Returns a string value for the color. The returned result is the smallest possible hex notation.
Parameters
Examples
// Styles as object usage
const styles = {
background: hsl(359, 0.75, 0.4),
background: hsl({ hue: 360, saturation: 0.75, lightness: 0.4 }),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${hsl(359, 0.75, 0.4)};
background: ${hsl({ hue: 360, saturation: 0.75, lightness: 0.4 })};
`
// CSS in JS Output
element {
background: "#b3191c";
background: "#b3191c";
}
Returns string
function hsla
Returns a string value for the color. The returned result is the smallest possible rgba or hex notation.
Parameters
Examples
// 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),
}
// syled (CSS in JS) 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";
}
Returns string
function 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
.
Parameters
Examples
// 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 }),
}
// syled (CSS in JS) 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)";
}
Returns string
function invert
Inverts the red, green and blue values of a color.
Parameters
color
string
Examples
// Styles as object usage
const styles = {
background: invert('#CCCD64'),
background: invert('rgba(101,100,205,0.7)'),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${invert('#CCCD64')};
background: ${invert('rgba(101,100,205,0.7)')};
`
// CSS in JS Output
element {
background: "#33329b";
background: "rgba(154,155,50,0.7)";
}
Returns string
function lighten
Returns a string value for the lightened color.
Parameters
Examples
// Styles as object usage
const styles = {
background: lighten(0.2, '#CCCD64'),
background: lighten('0.2', 'rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) 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)";
}
Returns string
function 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.
Parameters
Examples
// 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')
}
// syled (CSS in JS) 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)";
}
Returns string
function opacify
Increases the opacity of a color. Its range for the amount is between 0 to 1.
Parameters
Examples
// 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)'),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${opacify(0.1, 'rgba(255, 255, 255, 0.9)')};
background: ${opacify(0.2, 'hsla(0, 0%, 100%, 0.5)')},
background: ${opacify('0.5', 'rgba(255, 0, 0, 0.2)')},
`
// CSS in JS Output
element {
background: "#fff";
background: "rgba(255,255,255,0.7)";
background: "rgba(255,0,0,0.7)";
}
Returns string
function 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.
Parameters
color
string
Examples
// 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)');
Returns (HslColor | HslaColor)
function 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.
Parameters
color
string
Examples
// 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)');
Returns (RgbColor | RgbaColor)
function readableColor
Returns black or white (or optional light and dark return colors) for best contrast depending on the luminosity of the given color. Follows W3C specs for readability.
Parameters
color
stringlightReturnColor
string (optional, default'#000'
)darkReturnColor
string (optional, default'#fff'
)
Examples
// Styles as object usage
const styles = {
color: readableColor('#000'),
color: readableColor('black', '#001', '#ff8'),
color: readableColor('white', '#001', '#ff8'),
}
// syled (CSS in JS) usage
const div = styled.div`
color: ${readableColor('#000')};
color: ${readableColor('black', '#001', '#ff8')};
color: ${readableColor('white', '#001', '#ff8')};
`
// CSS in JS Output
element {
color: "#fff";
color: "#ff8";
color: "#001";
}
Returns string
function rgb
Returns a string value for the color. The returned result is the smallest possible hex notation.
Parameters
Examples
// Styles as object usage
const styles = {
background: rgb(255, 205, 100),
background: rgb({ red: 255, green: 205, blue: 100 }),
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${rgb(255, 205, 100)};
background: ${rgb({ red: 255, green: 205, blue: 100 })};
`
// CSS in JS Output
element {
background: "#ffcd64";
background: "#ffcd64";
}
Returns string
function 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.
Parameters
Examples
// 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),
}
// syled (CSS in JS) 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)";
}
Returns string
function 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
.
Parameters
Examples
// 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 }),
}
// syled (CSS in JS) 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)";
}
Returns string
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
background: saturate(0.2, '#CCCD64'),
background: saturate('0.2', 'rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) 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)";
}
Returns string
function setHue
Sets the hue of a color to the provided value. The hue range can be from 0 and 359.
Parameters
Examples
// Styles as object usage
const styles = {
background: setHue(42, '#CCCD64'),
background: setHue('244', 'rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) 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)";
}
Returns string
function setLightness
Sets the lightness of a color to the provided value. The lightness range can be from 0 and 1.
Parameters
Examples
// Styles as object usage
const styles = {
background: setLightness(0.2, '#CCCD64'),
background: setLightness('0.75', 'rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) 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)";
}
Returns string
function setSaturation
Sets the saturation of a color to the provided value. The saturation range can be from 0 and 1.
Parameters
Examples
// Styles as object usage
const styles = {
background: setSaturation(0.2, '#CCCD64'),
background: setSaturation('0.75', 'rgba(204,205,100,0.7)'),
}
// syled (CSS in JS) 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)";
}
Returns string
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
background: shade(0.25, '#00f')
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${shade(0.25, '#00f')};
`
// CSS in JS Output
element {
background: "#00003f";
}
Returns string
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
background: tint(0.25, '#00f')
}
// syled (CSS in JS) usage
const div = styled.div`
background: ${tint(0.25, '#00f')};
`
// CSS in JS Output
element {
background: "#bfbfff";
}
Returns string
function 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
.
Parameters
color
Object
Examples
// 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 }),
}
// syled (CSS in JS) 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)";
}
Returns string
function transparentize
Decreases the opacity of a color. Its range for the amount is between 0 to 1.
Parameters
Examples
// 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)'),
}
// syled (CSS in JS) 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)";
}
Returns string
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
...directionalProperty('padding', '12px', '24px', '36px', '48px')
}
// syled (CSS in JS) usage
const div = styled.div`
${directionalProperty('padding', '12px', '24px', '36px', '48px')}
`
// CSS as JS Output
div {
'paddingTop': '12px',
'paddingRight': '24px',
'paddingBottom': '36px',
'paddingLeft': '48px'
}
Returns Styles
function em
Convert pixel value to ems. The default base value is 16px, but can be changed by passing a second argument to the function.
Type: function (value: (string | number), base: (string | number)): string
Parameters
Examples
// Styles as object usage
const styles = {
'height': em('16px')
}
// syled (CSS in JS) usage
const div = styled.div`
height: ${em('16px')}
`
// CSS in JS Output
element {
'height': '1em'
}
function getValueAndUnit
Returns a given CSS value and its unit as elements of an array.
Parameters
value
string
Examples
// Styles as object usage
const styles = {
'--dimension': getValueAndUnit('100px')[0],
'--unit': getValueAndUnit('100px')[1],
}
// syled (CSS in JS) usage
const div = styled.div`
--dimension: ${getValueAndUnit('100px')[0]};
--unit: ${getValueAndUnit('100px')[1]};
`
// CSS in JS Output
element {
'--dimension': 100,
'--unit': 'px',
}
Returns [(number | string), (string | void)]
Meta
- deprecated: getValueAndUnit has been marked for deprecation in polished 3.0 and will be fully deprecated in 4.0. It's functionality has been been moved to stripUnit as an optional return.
function 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.
Parameters
steps
numberbase
(number | string) (optional, default'1em'
)ratio
ModularScaleRatio (optional, default1.333
)
Examples
// Styles as object usage
const styles = {
// Increment two steps up the default scale
'fontSize': modularScale(2)
}
// syled (CSS in JS) usage
const div = styled.div`
// Increment two steps up the default scale
fontSize: ${modularScale(2)}
`
// CSS in JS Output
element {
'fontSize': '1.77689em'
}
Returns string
function rem
Convert pixel value to rems. The default base value is 16px, but can be changed by passing a second argument to the function.
Type: function (value: (string | number), base: (string | number)): string
Parameters
Examples
// Styles as object usage
const styles = {
'height': rem('16px')
}
// syled (CSS in JS) usage
const div = styled.div`
height: ${rem('16px')}
`
// CSS in JS Output
element {
'height': '1rem'
}
function stripUnit
Returns a given CSS value minus its unit (or the original value if an invalid string is passed). Optionally returns an array containing the stripped value and the original unit of measure.
Parameters
Examples
// Styles as object usage
const styles = {
'--dimension': stripUnit('100px'),
'--unit': stripUnit('100px')[1],
}
// syled (CSS in JS) usage
const div = styled.div`
--dimension: ${stripUnit('100px')};
--unit: ${stripUnit('100px')[1]};
`
// CSS in JS Output
element {
'--dimension': 100,
'--unit': 'px',
}
Returns any
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
fontSize: math('12rem + 8rem'),
fontSize: math('(12px + 2px) * 3'),
fontSize: math('3px^2 + sqrt(4)'),
}
// syled (CSS in JS) 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',
}
Returns string
function 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').
Parameters
fromSize
stringtoSize
stringminScreen
string (optional, default'320px'
)maxScreen
string (optional, default'1200px'
)
Examples
// Styles as object usage
const styles = {
fontSize: between('20px', '100px', '400px', '1000px'),
fontSize: between('20px', '100px')
}
// syled (CSS in JS) 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)'
}
Returns string
function clearFix
CSS to contain a float (credit to CSSMojo).
Parameters
parent
string (optional, default'&'
)
Examples
// Styles as object usage
const styles = {
...clearFix(),
}
// syled (CSS in JS) usage
const div = styled.div`
${clearFix()}
`
// CSS as JS Output
'&::after': {
'clear': 'both',
'content': '""',
'display': 'table'
}
Returns Styles
function cover
CSS to fully cover an area. Can optionally be passed an offset to act as a "padding".
Parameters
Examples
// Styles as object usage
const styles = {
...cover()
}
// syled (CSS in JS) usage
const div = styled.div`
${cover()}
`
// CSS as JS Output
div: {
'position': 'absolute',
'top': '0',
'right: '0',
'bottom': '0',
'left: '0'
}
Returns Styles
function ellipsis
CSS to represent truncated text with an ellipsis.
Parameters
Examples
// Styles as object usage
const styles = {
...ellipsis('250px')
}
// syled (CSS in JS) 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'
}
Returns Styles
function 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.
Parameters
cssProp
(Array<FluidRangeConfiguration> | FluidRangeConfiguration)minScreen
string (optional, default'320px'
)maxScreen
string (optional, default'1200px'
)
Examples
// Styles as object usage
const styles = {
...fluidRange(
{
prop: 'padding',
fromSize: '20px',
toSize: '100px',
},
'400px',
'1000px',
)
}
// syled (CSS in JS) 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",
}
Returns Styles
function fontFace
CSS for a @font-face declaration.
Parameters
$0
any$0.fontFamily
$0.fontFilePath
$0.fontStretch
$0.fontStyle
$0.fontVariant
$0.fontWeight
$0.fileFormats
(optional, default['eot','woff2','woff','ttf','svg']
)$0.formatHint
(optional, defaultfalse
)$0.localFonts
$0.unicodeRange
$0.fontDisplay
$0.fontVariationSettings
$0.fontFeatureSettings
Examples
// 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")',
}
Returns Styles
function hideText
CSS to hide text to show a background image in a SEO-friendly way.
Examples
// Styles as object usage
const styles = {
'backgroundImage': 'url(logo.png)',
...hideText(),
}
// syled (CSS in JS) 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',
}
Returns Styles
function hideVisually
CSS to hide content visually but remain accessible to screen readers. from HTML5 Boilerplate
Examples
// Styles as object usage
const styles = {
...hideVisually(),
}
// syled (CSS in JS) usage
const div = styled.div`
${hideVisually()};
`
// CSS as JS Output
'div': {
'border': '0',
'clip': 'rect(0 0 0 0)',
'clipPath': 'inset(50%)',
'height': '1px',
'margin': '-1px',
'overflow': 'hidden',
'padding': '0',
'position': 'absolute',
'whiteSpace': 'nowrap',
'width': '1px',
}
Returns Styles
function hiDPI
Generates a media query to target HiDPI devices.
Parameters
ratio
number (optional, default1.3
)
Examples
// Styles as object usage
const styles = {
[hiDPI(1.5)]: {
width: 200px;
}
}
// syled (CSS in JS) 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',
}
Returns string
function 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.
Parameters
$0
any$0.colorStops
$0.fallback
$0.toDirection
(optional, default''
)
Examples
// Styles as object usage
const styles = {
...linearGradient({
colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
toDirection: 'to top right',
fallback: '#FFF',
})
}
// syled (CSS in JS) 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%)',
}
Returns Styles
function normalize
CSS to normalize abnormalities across browsers (normalize.css v8.0.0 | MIT License | github.com/necolas/normalize.css)
Examples
// Styles as object usage
const styles = {
...normalize(),
}
// syled (CSS in JS) usage
const GlobalStyle = createGlobalStyle`${normalize()}`
// CSS as JS Output
html {
lineHeight: 1.15,
textSizeAdjust: 100%,
} ...
function 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.
Parameters
$0
any$0.colorStops
$0.extent
(optional, default''
)$0.fallback
$0.position
(optional, default''
)$0.shape
(optional, default''
)
Examples
// 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',
})
}
// syled (CSS in JS) 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%)',
}
Returns Styles
function 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.
Parameters
filename
stringbackgroundSize
stringextension
string (optional, default'png'
)retinaFilename
stringretinaSuffix
string (optional, default'_2x'
)
Examples
// Styles as object usage
const styles = {
...retinaImage('my-img')
}
// syled (CSS in JS) 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)',
}
}
Returns Styles
function timingFunctions
String to represent common easing functions as demonstrated here: (github.com/jaukia/easie).
Parameters
timingFunction
TimingFunction
Examples
// Styles as object usage
const styles = {
'transitionTimingFunction': timingFunctions('easeInQuad')
}
// syled (CSS in JS) usage
const div = styled.div`
transitionTimingFunction: ${timingFunctions('easeInQuad')};
`
// CSS as JS Output
'div': {
'transitionTimingFunction': 'cubic-bezier(0.550, 0.085, 0.680, 0.530)',
}
Returns string
function triangle
CSS to represent triangle with any pointing direction with an optional background color.
Parameters
$0
any$0.pointingDirection
$0.height
$0.width
$0.foregroundColor
$0.backgroundColor
(optional, default'transparent'
)
Examples
// Styles as object usage
const styles = {
...triangle({ pointingDirection: 'right', width: '100px', height: '100px', foregroundColor: 'red' })
}
// syled (CSS in JS) 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',
}
Returns Styles
function wordWrap
Provides an easy way to change the wordWrap
property.
Parameters
wrap
string (optional, default'break-word'
)
Examples
// Styles as object usage
const styles = {
...wordWrap('break-word')
}
// syled (CSS in JS) usage
const div = styled.div`
${wordWrap('break-word')}
`
// CSS as JS Output
const styles = {
overflowWrap: 'break-word',
wordWrap: 'break-word',
wordBreak: 'break-all',
}
Returns Styles
function animation
Shorthand for easily setting the animation property. Allows either multiple arrays with animations or a single animation spread over the arguments.
Parameters
Examples
// Styles as object usage
const styles = {
...animation(['rotate', '1s', 'ease-in-out'], ['colorchange', '2s'])
}
// syled (CSS in JS) 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')
}
// syled (CSS in JS) usage
const div = styled.div`
${animation('rotate', '1s', 'ease-in-out')}
`
// CSS as JS Output
div {
'animation': 'rotate 1s ease-in-out'
}
Returns Styles
function backgroundImages
Shorthand that accepts any number of backgroundImage values as parameters for creating a single background statement.
Parameters
Examples
// Styles as object usage
const styles = {
...backgroundImages('url("/image/background.jpg")', 'linear-gradient(red, green)')
}
// syled (CSS in JS) 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)'
}
Returns Styles
function backgrounds
Shorthand that accepts any number of background values as parameters for creating a single background statement.
Parameters
Examples
// Styles as object usage
const styles = {
...backgrounds('url("/image/background.jpg")', 'linear-gradient(red, green)', 'center no-repeat')
}
// syled (CSS in JS) 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'
}
Returns Styles
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
...border('1px', 'solid', 'red')
}
// syled (CSS in JS) 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')
}
// syled (CSS in JS) usage
const div = styled.div`
${border('top', '1px', 'solid', 'red')}
`
// CSS as JS Output
div {
'borderTopColor': 'red',
'borderTopStyle': 'solid',
'borderTopWidth': `1px`,
}
Returns Styles
function borderColor
Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.
Parameters
Examples
// Styles as object usage
const styles = {
...borderColor('red', 'green', 'blue', 'yellow')
}
// syled (CSS in JS) usage
const div = styled.div`
${borderColor('red', 'green', 'blue', 'yellow')}
`
// CSS as JS Output
div {
'borderTopColor': 'red',
'borderRightColor': 'green',
'borderBottomColor': 'blue',
'borderLeftColor': 'yellow'
}
Returns Styles
function borderRadius
Shorthand that accepts a value for side and a value for radius and applies the radius value to both corners of the side.
Parameters
Examples
// Styles as object usage
const styles = {
...borderRadius('top', '5px')
}
// syled (CSS in JS) usage
const div = styled.div`
${borderRadius('top', '5px')}
`
// CSS as JS Output
div {
'borderTopRightRadius': '5px',
'borderTopLeftRadius': '5px',
}
Returns Styles
function borderStyle
Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.
Parameters
Examples
// Styles as object usage
const styles = {
...borderStyle('solid', 'dashed', 'dotted', 'double')
}
// syled (CSS in JS) usage
const div = styled.div`
${borderStyle('solid', 'dashed', 'dotted', 'double')}
`
// CSS as JS Output
div {
'borderTopStyle': 'solid',
'borderRightStyle': 'dashed',
'borderBottomStyle': 'dotted',
'borderLeftStyle': 'double'
}
Returns Styles
function borderWidth
Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.
Parameters
Examples
// Styles as object usage
const styles = {
...borderWidth('12px', '24px', '36px', '48px')
}
// syled (CSS in JS) usage
const div = styled.div`
${borderWidth('12px', '24px', '36px', '48px')}
`
// CSS as JS Output
div {
'borderTopWidth': '12px',
'borderRightWidth': '24px',
'borderBottomWidth': '36px',
'borderLeftWidth': '48px'
}
Returns Styles
function buttons
Populates selectors that target all buttons. You can pass optional states to append to the selectors.
Parameters
states
...Array<InteractionState>
Examples
// Styles as object usage
const styles = {
[buttons('active')]: {
'border': 'none'
}
}
// syled (CSS in JS) 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'
}
Returns string
function margin
Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.
Parameters
Examples
// Styles as object usage
const styles = {
...margin('12px', '24px', '36px', '48px')
}
// syled (CSS in JS) usage
const div = styled.div`
${margin('12px', '24px', '36px', '48px')}
`
// CSS as JS Output
div {
'marginTop': '12px',
'marginRight': '24px',
'marginBottom': '36px',
'marginLeft': '48px'
}
Returns Styles
function padding
Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective directions.
Parameters
Examples
// Styles as object usage
const styles = {
...padding('12px', '24px', '36px', '48px')
}
// syled (CSS in JS) usage
const div = styled.div`
${padding('12px', '24px', '36px', '48px')}
`
// CSS as JS Output
div {
'paddingTop': '12px',
'paddingRight': '24px',
'paddingBottom': '36px',
'paddingLeft': '48px'
}
Returns Styles
function 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.
Parameters
Examples
// Styles as object usage
const styles = {
...position('12px', '24px', '36px', '48px')
}
// syled (CSS in JS) 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')
}
// syled (CSS in JS) 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'
}
Returns Styles
CSSHelpers
function topShadow
Computes a material design style top shadow effect to mimic depth.
Parameters
depth
number
Examples
// Styles as object usage
const styles = {
boxShadow: `${topShadow(0)}, ${topShadow(1)}`
}
// syled (CSS in JS) usage
const div = styled.div`
box-shadow: ${topShadow(0)}, ${topShadow(1)};
`
// CSS as JS Output
div {
'box-shadow': '0 2px 0 rgba(18, 23, 28, 0.012), 0 4px 3px rgba(18, 23, 28, 0.016)'
}
function bottomShadow
Computes a material design style bottom shadow effect to mimic depth.
Parameters
depth
number
Examples
// Styles as object usage
const styles = {
boxShadow: `${bottomShadow(0)}, ${bottomShadow(1)}`
}
// syled (CSS in JS) usage
const div = styled.div`
box-shadow: ${bottomShadow(0)}, ${bottomShadow(1)};
`
// CSS as JS Output
div {
'box-shadow': '0 0.5px 0.5px rgba(18, 23, 28, 0.017), 0 1.5px 1px rgba(18, 23, 28, 0.024)'
}
function size
Shorthand to set the height