@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
adjustHue
function 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
complement
function 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
darken
function 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
desaturate
function 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
getLuminance
function 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
grayscale
function 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
hsl
function 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
hsla
function 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
hslToColorString
function 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
invert
function 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
lighten
function 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
mix
function 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
opacify
function 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
parseToHsl
function 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)
parseToRgb
function 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)
readableColor
function 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
string -
lightReturnColor
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
rgb
function 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
rgba
function 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
rgbToColorString
function 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
saturate
function 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
setHue
function 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
setLightness
function 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
setSaturation
function 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
shade
function 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
tint
function 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
toColorString
function 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
transparentize
function 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
directionalProperty
function 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
em
function 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'
}
getValueAndUnit
function 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.
modularScale
function 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
number -
base
(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
rem
function 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'
}
stripUnit
function 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
math
function 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
between
function 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
string -
toSize
string -
minScreen
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
clearFix
function 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
cover
function 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
ellipsis
function 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
fluidRange
function 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
fontFace
function 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
hideText
function 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
hideVisually
function 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
hiDPI
function 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
linearGradient
function 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
normalize
function 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%,
} ...
radialGradient
function 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
retinaImage
function 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
string -
backgroundSize
string -
extension
string (optional, default'png'
) -
retinaFilename
string -
retinaSuffix
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
timingFunctions
function 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
triangle
function 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
wordWrap
function 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
animation
function 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
backgroundImages
function 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
backgrounds
function 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
border
function 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
borderColor
function 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
borderRadius
function 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
borderStyle
function 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
borderWidth
function 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
buttons
function 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
margin
function 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
padding
function 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
position
function 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
topShadow
function 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)'
}
bottomShadow
function 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)'
}
size
function Shorthand to set the height and width properties in a single statement.
Parameters
Examples
// Styles as object usage
const styles = {
...size('300px', '250px')
}
// syled (CSS in JS) usage
const div = styled.div`
${size('300px', '250px')}
`
// CSS as JS Output
div {
'height': '300px',
'width': '250px',
}
Returns Styles
textInputs
function Populates selectors that target all text inputs. You can pass optional states to append to the selectors.
Parameters
-
states
...Array<InteractionState>
Examples
// Styles as object usage
const styles = {
[textInputs('active')]: {
'border': 'none'
}
}
// syled (CSS in JS) 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'
}
Returns string
transitions
function 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).
Parameters
Examples
// 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')
}
// syled (CSS in JS) 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',
}
Returns Styles
HslColor
Type: {hue: number, saturation: number, lightness: number}
Properties
HslaColor
Type: {hue: number, saturation: number, lightness: number, alpha: number}
Properties
RgbColor
Type: {red: number, green: number, blue: number}
Properties
RgbaColor
Type: {red: number, green: number, blue: number, alpha: number}
Properties
FluidRangeConfiguration
Type: {prop: string, fromSize: string, toSize: string}
Properties
FontFaceConfiguration
Type: {fontFamily: string, fontFilePath: string?, fontStretch: string?, fontStyle: string?, fontVariant: string?, fontWeight: string?, fileFormats: Array<string>?, formatHint: boolean?, localFonts: Array<string>?, unicodeRange: string?, fontDisplay: string?, fontVariationSettings: string?, fontFeatureSettings: string?}
Properties
-
fontFamily
string -
fontFilePath
string? -
fontStretch
string? -
fontStyle
string? -
fontVariant
string? -
fontWeight
string? -
fileFormats
Array<string>? -
formatHint
boolean? -
localFonts
Array<string>? -
unicodeRange
string? -
fontDisplay
string? -
fontVariationSettings
string? -
fontFeatureSettings
string?
InteractionState
Type: (any | null | "active"
| "focus"
| "hover"
)
LinearGradientConfiguration
Type: {colorStops: Array<string>, toDirection: string?, fallback: string?}
Properties
ModularScaleRatio
Type: (number | "minorSecond"
| "majorSecond"
| "minorThird"
| "majorThird"
| "perfectFourth"
| "augFourth"
| "perfectFifth"
| "minorSixth"
| "goldenSection"
| "majorSixth"
| "minorSeventh"
| "majorSeventh"
| "octave"
| "majorTenth"
| "majorEleventh"
| "majorTwelfth"
| "doubleOctave"
)
RadialGradientConfiguration
Type: {colorStops: Array<string>, extent: string?, fallback: string?, position: string?, shape: string?}
Properties
SideKeyword
Type: ("top"
| "topRight"
| "right"
| "bottomRight"
| "bottom"
| "bottomLeft"
| "left"
| "topLeft"
)
Styles
Type: {}
Properties
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"
)
TriangleConfiguration
Type: {backgroundColor: string?, foregroundColor: string, height: (number | string), width: (number | string), pointingDirection: SideKeyword}
Properties
-
backgroundColor
number -
foregroundColor
number -
height
number -
height
number -
height
number -
width
(number | string) -
pointingDirection
SideKeyword
Contribute
- Fork it and create your feature branch:
git checkout -b my-new-feature
- Commit your changes:
git commit -am "Add some feature"
- Push to the branch:
git push origin my-new-feature
- Submit a pull request
License
MIT © SiteOne, contributors, sourced packages authors & contributors