@theme-ui/color

@theme-ui/color

Color manipulation utilities for Theme UI

npm i @theme-ui/color

Import utilities from the @theme-ui/color package and use them with colors in the sx prop.

/** @jsx jsx */
import { jsx } from 'theme-ui'
import { darken, lighten } from '@theme-ui/color'

export default props => (
  <div
    {...props}
    sx={{
      color: darken('primary', 0.25),
      bg: lighten('primary', 0.875),
    }}
  />
)

API

getColor

import { getColor } from '@theme-ui/color'
// getColor(theme, 'primary')

darken

Darken a color by an amount 0–1

import { darken } from '@theme-ui/color'
// darken('primary', amount)

lighten

Lighten a color by an amount 0–1

import { lighten } from '@theme-ui/color'
// lighten('primary', amount)

rotate

Rotate the hue of a color by an amount 0–360

import { rotate } from '@theme-ui/color'
// rotate('primary', degrees)

hue

Set the hue of a color to a degree 0–360

import { hue } from '@theme-ui/color'
// hue('primary', degrees)

saturation

Set the saturation of a color to an amount 0–1

import { saturation } from '@theme-ui/color'
// saturation('primary', amount)

lightness

Set the lightness of a color to an amount 0–1

import { lightness } from '@theme-ui/color'
// lightness('primary', amount)

desaturate

Desaturate a color by an amount 0–1

import { desaturate } from '@theme-ui/color'
// desaturate('primary', amount)

saturate

Saturate a color by an amount 0–1

import { saturate } from '@theme-ui/color'
// saturate('primary', amount)

shade

Shade a color by an amount 0–1

import { shade } from '@theme-ui/color'
// shade('primary', amount)

tint

Tint a color by an amount 0–1

import { tint } from '@theme-ui/color'
// tint('primary', amount)

alpha

Set the transparency of a color to an amount 0-1

import { alpha } from '@theme-ui/color'
// alpha('primary', amount)

transparentize

Similar to alpha, but decreases opacity by the given amount.

import { transparentize } from '@theme-ui/color'
// transparentize('primary', amount)

mix

Mix two colors by a specific ratio

import { mix } from '@theme-ui/color'
// mix('primary', 'secondary', ratio)

complement

Get the complement of a color

import { complement } from '@theme-ui/color'
// complement('primary')

invert

Get the inverted color

import { invert } from '@theme-ui/color'
// invert('primary')

grayscale

Desaturate the color to grayscale

import { grayscale } from '@theme-ui/color'
// grayscale('primary')

Advanced Usage

If you want to do something more complex, such as setting up gradients, you can do that with some extra workarounds.

We can take the result of any of the above helper functions (which return a function) and call it with the theme object to generate a string in place. This is useful for interpolating values into complex CSS declarations:

<MyComponentWithBackground
  sx={{
    backgroundImage: t => `
      linear-gradient(
        to bottom,
        ${alpha('primary', 0.5)(t)},
        ${alpha('secondary', 0.5)(t)}
      )
    `,
  }}
/>

Related

• Polished

Changelog

v0.4.0-rc.8 2020-11-09

@theme-ui/color

• Fix support for rgb/hsl color values

@theme-ui/components

• Add Switch component #1035

  <Label>
    <Switch /> Enable email alerts?
  </Label>
  

• Pass size prop down to IconButton in Close component. PR #1242

  <Close size={24} />
  

examples

• Convert Gatsby example to TypeScript and stop using removed components. Issue #1227, PR #1229