Chroma is a color manipulation and palette generation library. It is heavily inspired by and a very close Ruby port of the tinycolor.js library. Many thanks to Brian Grinstead for his hard work on that library.
Please don't hesitate to examine the code and make issues, feature requests, or pull requests. Please refer to the Contributing section below.
Add this line to your application's Gemfile:
gem 'chroma'
And then execute:
$ bundle
Or install it yourself as:
$ gem install chroma
Colors are created via the Chroma.paint method. It expects any one of
many possible color formats as a string, including names, hexadecimal, rgb,
hsl, and hsv. As a convenience, a String#paint is also available for more
succinct color creation.
# With Chroma.paint
Chroma.paint 'red' # named colors
Chroma.paint '#00ff00' # 6 character hexadecimal
Chroma.paint '#00f' # 3 character hexadecimal
Chroma.paint 'rgb(255, 255, 0)' # rgb
Chroma.paint 'rgba(255, 255, 0, 0.5)' # rgba
Chroma.paint 'hsl(60, 100%, 50%)' # hsl with percentages
Chroma.paint 'hsl(60, 1, 0.5)' # hsl with decimals
Chroma.paint 'hsla(60, 100%, 50%, 0.5)' # hsla
Chroma.paint 'hsv(60, 100%, 50%)' # hsv with percentages
Chroma.paint 'hsv(60, 1, 0.5)' # hsv with decimals
Chroma.paint 'hsva(60, 100%, 50%, 0.75)' # hsva
# With String#paint
'red'.paint
'#00ff00'.paint
'#00f'.paint
'rgb(255, 255, 0)'.paint
'rgba(255, 255, 0, 0.5)'.paint
'hsl(60, 100%, 50%)'.paint
'hsla(60, 100%, 50%, 0.5)'.paint
'hsv(60, 100%, 50%)'.paint
'hsva(60, 100%, 50%. 0.5)'.paint
Chroma's major strength is manipulating colors and generating color palettes, which allows you to easily generate dynamic colors, dynamic themes for a web application, and more.
Lighten the color by a given amount. Defaults to 10.
'red'.paint.lighten #=> #ff3333
'red'.paint.lighten(20) #=> #ff6666
Brighten the color by a given amount. Defaults to 10.
'red'.paint.brighten #=> #ff1a1a
'red'.paint.brighten(20) #=> #ff3333
Darken the color by a given amount. Defaults to 10.
'red'.paint.darken #=> #cc0000
'red'.paint.darken(20) #=> #990000
Desaturate the color by a given amount. Defaults to 10.
'red'.paint.desaturate #=> #f20d0d
'red'.paint.desaturate(20) #=> #e61919
Saturate the color by a given amount. Defaults to 10.
'#123'.paint.saturate #=> #0e2236
'#123'.paint.saturate(20) #=> #0a223a
Convert the color to grayscale.
'green'.paint.grayscale #=> #404040
# greyscale is an alias
'red'.paint.greyscale #=> #808080
Set the opacity of the color to a given amount.
'red'.paint.opacity(0.3) #=> #ff0000
'red'.paint.opacity(0.3).to_rgb #=> 'rgba(255, 0, 0, 0.3)'
Spin a given amount in degrees around the hue wheel.
'red'.paint.spin(30) #=> #ff8000
'red'.paint.spin(60) #=> yellow
'red'.paint.spin(90) #=> #80ff00
Chroma's most powerful feature is palette generation. You can use the default palettes available or even create your own custom palettes.
Palette methods are available via Color#palette and by default output an
array of colors. If you want the underlying color strings, you can pass in
the desired format via the :as option.
Generate a complement palette.
'red'.paint.palette.complement #=> [red, cyan]
'red'.paint.palette.complement(as: :name) #=> ['red', 'cyan']
'red'.paint.palette.complement(as: :hex) #=> ['#ff0000', '#00ffff']
Generate a triad palette.
'red'.paint.palette.triad #=> [red, lime, blue]
'red'.paint.palette.triad(as: :name) #=> ['red', 'lime', 'blue']
'red'.paint.palette.triad(as: :hex) #=> ['#ff0000', '#00ff00', '#0000ff']
Generate a tetrad palette.
'red'.paint.palette.tetrad
#=> [red, #80ff00, cyan, #7f00ff]
'red'.paint.palette.tetrad(as: :name)
#=> ['red', '#80ff00', 'cyan', '#7f00ff']
'red'.paint.palette.tetrad(as: :hex)
#=> ['#ff0000', '#80ff00', '#00ffff', '#7f00ff']
Generate a split complement palette.
'red'.paint.palette.split_complement
#=> [red, #ccff00, #0066ff]
'red'.paint.palette.split_complement(as: :name)
#=> ['red', '#ccff00', '#0066ff']
'red'.paint.palette.split_complement(as: :hex)
#=> ['#ff0000', '#ccff00', '#0066ff']
Generate an analogous palette. Pass in a :size option to specify the size
of the palette (defaults to 6). Pass in a :slice_by option to specify the
angle size to slice into the hue wheel (defaults to 30 degrees).
'red'.paint.palette.analogous
#=> [red, #ff0066, #ff0033, red, #ff3300, #ff6600]
'red'.paint.palette.analogous(as: :hex)
#=> ['#f00', '#f06', '#f03', '#f00', '#f30', '#f60']
'red'.paint.palette.analogous(size: 3)
#=> [red, #ff001a, #ff1a00]
'red'.paint.palette.analogous(size: 3, slice_by: 60)
#=> [red, #ff000d, #ff0d00]
Generate a monochromatic palette. Pass in a :size option to specify the size
of the palette (defaults to 6).
'red'.paint.palette.monochromatic
#=> [red, #2a0000, #550000, maroon, #aa0000, #d40000]
'red'.paint.palette.monochromatic(as: :hex)
#=> ['#ff0000', '#2a0000', '#550000', '#800000', '#aa0000', '#d40000']
'red'.paint.palette.monochromatic(size: 3)
#=> [red, #550000, #aa0000]
Chroma allows you to define your own custom palettes if the default ones aren't
all you're looking for. You can define a custom palette by calling
Chroma.define_palette, passing in a palette name and definition block. The
definition block uses the color manipulation methods (i.e. lighten, spin,
etc.) as its DSL. Every DSL call defines a new color that will be included
in the palette. Your seed color (i.e. the color from which you call the
palette method) will be included as the first color in your palette too.
red = 'red'.paint
red.palette.respond_to? :my_palette #=> false
# Define a palette with 5 colors including the seed color
Chroma.define_palette :my_palette do
spin 60
spin 180
spin(60).brighten(20) # chain calls as well
greyscale
end
red.palette.respond_to? :my_palette #=> true
red.palette.my_palette #=> [#ff0000 #ffff00 #00ffff #ffff33 #808080]
You can generate custom palettes on the fly too with
Chroma::Color#custom_palette.
'red'.paint.custom_palette do
spin 60
spin 180
end
#=> [red, yellow, cyan]
Colors offer several methods to output to different string color formats.
| Method | Description |
|---|---|
to_hsv | output to hsv string, outputs hsva if alpha < 1 |
to_hsl | output to hsl string, outputs hsla if alpha < 1 |
to_hex | output to hex string, optional argument allows 3-character hex output if possible |
to_hex8 | output to 8-character hex string with alpha value in the highest order byte |
to_rgb | output to rgb string, outputs rgba if alpha < 1 |
to_name | output to color name string if available, otherwise '<unknown>' or to_hex output based on optional arg value |
to_s | output to the appropriate string format based on how the color was created, optional arg forces the format |
# to_hsv
'red'.paint.to_hsv #=> 'hsv(0, 100%, 100%)'
'rgba(255, 0, 0, 0.5)'.paint.to_hsv #=> 'hsva(0, 100%, 100%, 0.5)'
# to_hsl
'red'.paint.to_hsl #=> 'hsl(0, 100%, 50%)'
'rgba(255, 0, 0, 0.5)'.paint.to_hsl #=> 'hsla(0, 100%, 50%, 0.5)'
# to_hex
'red'.paint.to_hex #=> '#ff0000'
'red'.paint.to_hex(true) #=> '#f00'
'rgba(255, 0, 0, 0.5)'.paint.to_hex #=> '#ff0000'
'red'.paint.to_hex #=> '#ffff0000'
'rgba(255, 0, 0, 0.5)'.paint.to_hex #=> '#80ff0000'
# to_rgb
'red'.paint.to_rgb #=> 'rgb(255, 0, 0)'
'rgba(255, 0, 0, 0.5)'.paint.to_rgb #=> 'rgb(255, 0, 0, 0.5)'
# to_name
'red'.paint.to_name #=> 'red'
'#00f'.paint.to_name #=> 'blue'
'rgba(255, 0, 0, 0.5)'.paint.to_name #=> '<unknown>'
'#123'.paint.to_name(true) #=> '#112233'
# to_s
'red'.paint.to_s #=> 'red'
'rgb(255, 0, 0)'.paint.to_s #=> 'rgb(255, 0, 0)'
'#f00'.paint.to_s #=> '#f00'
'#80ff0000'.paint.to_s(:rgb) #=> 'rgba(255, 0, 0, 0.5)'
Colors also have a few other helper methods:
| Method | Description |
|---|---|
dark? | is the color dark? |
light? | is the color light? |
alpha | retrieve the alpha value |
brightness | calculate the brightness as a number between 0 and 255 |
complement | return the complementary color |
# dark?
'red'.paint.dark? #=> true
'yellow'.paint.dark? #=> false
# light?
'red'.paint.light? #=> false
'yellow'.paint.light? #=> true
# alpha
'red'.paint.alpha #=> 1.0
'rgba(0, 0, 0, 0.5)'.paint.alpha #=> 0.5
# brightness
'red'.paint.brightness #=> 76.245
'yellow'.paint.brightness #=> 225.93
'white'.paint.brightness #=> 255.0
'black'.paint.brightness #=> 0.0
# complement
'red'.paint.complement #=> cyan
Please branch from dev for all pull requests.
git checkout dev)git checkout -b my-new-feature)git commit -am 'Add some feature')git push origin my-new-feature)FAQs
Unknown package
We found that chroma demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.