Enum Color

pub enum Color {
    Luma(Luma),
    Oklab(Oklab),
    Oklch(Oklch),
    Rgb(Rgb),
    LinearRgb(LinearRgb),
    Cmyk(Cmyk),
    Hsl(Hsl),
    Hsv(Hsv),
}

A color in a specific color space.

Typst supports:

• sRGB through the rgb function
• Device CMYK through cmyk function
• D65 Gray through the luma function
• Oklab through the oklab function
• Oklch through the oklch function
• Linear RGB through the color.linear-rgb function
• HSL through the color.hsl function
• HSV through the color.hsv function

Example

#rect(fill: aqua)

Predefined colors

Typst defines the following built-in colors:

Color	Definition
black	{luma(0)}
gray	{luma(170)}
silver	{luma(221)}
white	{luma(255)}
navy	{rgb("#001f3f")}
blue	{rgb("#0074d9")}
aqua	{rgb("#7fdbff")}
teal	{rgb("#39cccc")}
eastern	{rgb("#239dad")}
purple	{rgb("#b10dc9")}
fuchsia	{rgb("#f012be")}
maroon	{rgb("#85144b")}
red	{rgb("#ff4136")}
orange	{rgb("#ff851b")}
yellow	{rgb("#ffdc00")}
olive	{rgb("#3d9970")}
green	{rgb("#2ecc40")}
lime	{rgb("#01ff70")}

The predefined colors and the most important color constructors are available globally and also in the color type’s scope, so you can write either color.red or just red.

#let colors = (
  "black", "gray", "silver", "white",
  "navy", "blue", "aqua", "teal",
  "eastern", "purple", "fuchsia",
  "maroon", "red", "orange", "yellow",
  "olive", "green", "lime",
)

#set text(font: "PT Sans")
#set page(width: auto)
#grid(
  columns: 9,
  gutter: 10pt,
  ..colors.map(name => {
      let col = eval(name)
      let luminance = luma(col).components().first()
      set text(fill: white) if luminance < 50%
      set square(stroke: black) if col == white
      set align(center + horizon)
      square(size: 50pt,  fill: col, name)
  })
)

Predefined color maps

Typst also includes a number of preset color maps that can be used for gradients. These are simply arrays of colors defined in the module color.map.

#circle(fill: gradient.linear(..color.map.crest))

Map	Details
turbo	A perceptually uniform rainbow-like color map. Read this blog post for more details.
cividis	A blue to gray to yellow color map. See this blog post for more details.
rainbow	Cycles through the full color spectrum. This color map is best used by setting the interpolation color space to HSL. The rainbow gradient is not suitable for data visualization because it is not perceptually uniform, so the differences between values become unclear to your readers. It should only be used for decorative purposes.
spectral	Red to yellow to blue color map.
viridis	A purple to teal to yellow color map.
inferno	A black to red to yellow color map.
magma	A black to purple to yellow color map.
plasma	A purple to pink to yellow color map.
rocket	A black to red to white color map.
mako	A black to teal to yellow color map.
vlag	A light blue to white to red color map.
icefire	A light teal to black to yellow color map.
flare	A orange to purple color map that is perceptually uniform.
crest	A blue to white to red color map.

Some popular presets are not included because they are not available under a free licence. Others, like Jet, are not included because they are not color blind friendly. Feel free to use or create a package with other presets that are useful to you!

#set page(width: auto, height: auto)
#set text(font: "PT Sans", size: 8pt)

#let maps = (
  "turbo", "cividis", "rainbow", "spectral",
  "viridis", "inferno", "magma", "plasma",
  "rocket", "mako", "vlag", "icefire",
  "flare", "crest",
)

#stack(dir: ltr, spacing: 3pt, ..maps.map((name) => {
  let map = eval("color.map." + name)
  stack(
    dir: ttb,
    block(
      width: 15pt,
      height: 100pt,
      fill: gradient.linear(..map, angle: 90deg),
    ),
    block(
      width: 15pt,
      height: 32pt,
      move(dy: 8pt, rotate(90deg, name)),
    ),
  )
}))

Variants

Luma(Luma)

A 32-bit luma color.

Oklab(Oklab)

A 32-bit L*a*b* color in the Oklab color space.

Oklch(Oklch)

A 32-bit LCh color in the Oklab color space.

Rgb(Rgb)

A 32-bit RGB color.

LinearRgb(LinearRgb)

A 32-bit linear RGB color.

Cmyk(Cmyk)

A 32-bit CMYK color.

Hsl(Hsl)

A 32-bit HSL color.

Hsv(Hsv)

A 32-bit HSV color.

Implementations

impl Color

pub const MAP: fn() -> Module = {<{closure@src/visualize/color.rs:215:37: 215:39} as std::ops::FnOnce<()>>::call_once as fn() -> foundations::module::Module}

The module of preset color maps.

pub const BLACK: Self

pub const GRAY: Self

pub const WHITE: Self

pub const SILVER: Self

pub const NAVY: Self

pub const BLUE: Self

pub const AQUA: Self

pub const TEAL: Self

pub const EASTERN: Self

pub const PURPLE: Self

pub const FUCHSIA: Self

pub const MAROON: Self

pub const RED: Self

pub const ORANGE: Self

pub const YELLOW: Self

pub const OLIVE: Self

pub const GREEN: Self

pub const LIME: Self

pub fn luma(args: &mut Args) -> SourceResult<Color>

Create a grayscale color.

A grayscale color is represented internally by a single lightness component.

These components are also available using the components method.

#for x in range(250, step: 50) {
  box(square(fill: luma(x)))
}

pub fn oklab(args: &mut Args) -> SourceResult<Color>

Create an Oklab color.

This color space is well suited for the following use cases:

• Color manipulation such as saturating while keeping perceived hue
• Creating grayscale images with uniform perceived lightness
• Creating smooth and uniform color transition and gradients

A linear Oklab color is represented internally by an array of four components:

• lightness ([ratio])
• a ([float] or [ratio]. Ratios are relative to {0.4}; meaning {50%} is equal to {0.2})
• b ([float] or [ratio]. Ratios are relative to {0.4}; meaning {50%} is equal to {0.2})
• alpha ([ratio])

These components are also available using the components method.

#square(
  fill: oklab(27%, 20%, -3%, 50%)
)

pub fn oklch(args: &mut Args) -> SourceResult<Color>

Create an Oklch color.

This color space is well suited for the following use cases:

• Color manipulation involving lightness, chroma, and hue
• Creating grayscale images with uniform perceived lightness
• Creating smooth and uniform color transition and gradients

A linear Oklch color is represented internally by an array of four components:

• lightness ([ratio])
• chroma ([float] or [ratio]. Ratios are relative to {0.4}; meaning {50%} is equal to {0.2})
• hue ([angle])
• alpha ([ratio])

These components are also available using the components method.

#square(
  fill: oklch(40%, 0.2, 160deg, 50%)
)

pub fn linear_rgb(args: &mut Args) -> SourceResult<Color>

Create an RGB(A) color with linear luma.

This color space is similar to sRGB, but with the distinction that the color component are not gamma corrected. This makes it easier to perform color operations such as blending and interpolation. Although, you should prefer to use the oklab function for these.

A linear RGB(A) color is represented internally by an array of four components:

• red ([ratio])
• green ([ratio])
• blue ([ratio])
• alpha ([ratio])

These components are also available using the components method.

#square(fill: color.linear-rgb(
  30%, 50%, 10%,
))

pub fn rgb(args: &mut Args) -> SourceResult<Color>

Create an RGB(A) color.

The color is specified in the sRGB color space.

An RGB(A) color is represented internally by an array of four components:

• red ([ratio])
• green ([ratio])
• blue ([ratio])
• alpha ([ratio])

These components are also available using the components method.

#square(fill: rgb("#b1f2eb"))
#square(fill: rgb(87, 127, 230))
#square(fill: rgb(25%, 13%, 65%))

pub fn cmyk(args: &mut Args) -> SourceResult<Color>

Create a CMYK color.

This is useful if you want to target a specific printer. The conversion to RGB for display preview might differ from how your printer reproduces the color.

A CMYK color is represented internally by an array of four components:

• cyan ([ratio])
• magenta ([ratio])
• yellow ([ratio])
• key ([ratio])

These components are also available using the components method.

Note that CMYK colors are not currently supported when PDF/A output is enabled.

#square(
  fill: cmyk(27%, 0%, 3%, 5%)
)

pub fn hsl(args: &mut Args) -> SourceResult<Color>

Create an HSL color.

This color space is useful for specifying colors by hue, saturation and lightness. It is also useful for color manipulation, such as saturating while keeping perceived hue.

An HSL color is represented internally by an array of four components:

• hue ([angle])
• saturation ([ratio])
• lightness ([ratio])
• alpha ([ratio])

These components are also available using the components method.

#square(
  fill: color.hsl(30deg, 50%, 60%)
)

pub fn hsv(args: &mut Args) -> SourceResult<Color>

Create an HSV color.

This color space is useful for specifying colors by hue, saturation and value. It is also useful for color manipulation, such as saturating while keeping perceived hue.

An HSV color is represented internally by an array of four components:

• hue ([angle])
• saturation ([ratio])
• value ([ratio])
• alpha ([ratio])

These components are also available using the components method.

#square(
  fill: color.hsv(30deg, 50%, 60%)
)

pub fn components(self, alpha: bool) -> Array

Extracts the components of this color.

The size and values of this array depends on the color space. You can obtain the color space using space. Below is a table of the color spaces and their components:

Color space	C1	C2	C3	C4
luma	Lightness
oklab	Lightness	a	b	Alpha
oklch	Lightness	Chroma	Hue	Alpha
linear-rgb	Red	Green	Blue	Alpha
rgb	Red	Green	Blue	Alpha
cmyk	Cyan	Magenta	Yellow	Key
hsl	Hue	Saturation	Lightness	Alpha
hsv	Hue	Saturation	Value	Alpha

For the meaning and type of each individual value, see the documentation of the corresponding color space. The alpha component is optional and only included if the alpha argument is true. The length of the returned array depends on the number of components and whether the alpha component is included.

// note that the alpha component is included by default
#rgb(40%, 60%, 80%).components()

pub fn space(self) -> ColorSpace

Returns the constructor function for this color’s space:

• luma
• oklab
• oklch
• linear-rgb
• rgb
• cmyk
• hsl
• hsv

#let color = cmyk(1%, 2%, 3%, 4%)
#(color.space() == cmyk)

pub fn to_hex(self) -> EcoString

Returns the color’s RGB(A) hex representation (such as #ffaa32 or #020304fe). The alpha component (last two digits in #020304fe) is omitted if it is equal to ff (255 / 100%).

pub fn lighten(self, factor: Ratio) -> Color

Lightens a color by a given factor.

pub fn darken(self, factor: Ratio) -> Color

Darkens a color by a given factor.

pub fn saturate(self, span: Span, factor: Ratio) -> SourceResult<Color>

Increases the saturation of a color by a given factor.

pub fn desaturate(self, span: Span, factor: Ratio) -> SourceResult<Color>

Decreases the saturation of a color by a given factor.

pub fn negate(self, space: ColorSpace) -> Color

Produces the complementary color using a provided color space. You can think of it as the opposite side on a color wheel.

#square(fill: yellow)
#square(fill: yellow.negate())
#square(fill: yellow.negate(space: rgb))

pub fn rotate( self, span: Span, angle: Angle, space: ColorSpace, ) -> SourceResult<Color>

Rotates the hue of the color by a given angle.

pub fn mix(colors: Vec<WeightedColor>, space: ColorSpace) -> StrResult<Color>

Create a color by mixing two or more colors.

In color spaces with a hue component (hsl, hsv, oklch), only two colors can be mixed at once. Mixing more than two colors in such a space will result in an error!

#set block(height: 20pt, width: 100%)
#block(fill: red.mix(blue))
#block(fill: red.mix(blue, space: rgb))
#block(fill: color.mix(red, blue, white))
#block(fill: color.mix((red, 70%), (blue, 30%)))

pub fn transparentize(self, scale: Ratio) -> StrResult<Color>

Makes a color more transparent by a given factor.

This method is relative to the existing alpha value. If the scale is positive, calculates alpha - alpha * scale. Negative scales behave like color.opacify(-scale).

#block(fill: red)[opaque]
#block(fill: red.transparentize(50%))[half red]
#block(fill: red.transparentize(75%))[quarter red]

pub fn opacify(self, scale: Ratio) -> StrResult<Color>

Makes a color more opaque by a given scale.

This method is relative to the existing alpha value. If the scale is positive, calculates alpha + scale - alpha * scale. Negative scales behave like color.transparentize(-scale).

#let half-red = red.transparentize(50%)
#block(fill: half-red.opacify(100%))[opaque]
#block(fill: half-red.opacify(50%))[three quarters red]
#block(fill: half-red.opacify(-50%))[one quarter red]

impl Color

pub fn mix_iter( colors: impl IntoIterator<Item = WeightedColor, IntoIter = impl ExactSizeIterator<Item = WeightedColor>>, space: ColorSpace, ) -> StrResult<Color>

Same as Color::mix, but takes an iterator instead of a vector.

pub fn from_u8(r: u8, g: u8, b: u8, a: u8) -> Self

Construct a new RGBA color from 8-bit values.

pub fn from_u32(color: u32) -> Self

Converts a 32-bit integer to an RGBA color.

pub fn alpha(&self) -> Option<f32>

Returns the alpha channel of the color, if it has one.

pub fn with_alpha(self, alpha: f32) -> Self

Sets the alpha channel of the color, if it has one.

pub fn to_vec4(&self) -> [f32; 4]

Converts the color to a vec of four floats.

pub fn to_vec4_u8(&self) -> [u8; 4]

Converts the color to a vec of four u8s.

pub fn to_space(self, space: ColorSpace) -> Self

pub fn to_luma(self) -> Self

pub fn to_oklab(self) -> Self

pub fn to_oklch(self) -> Self

pub fn to_rgb(self) -> Self

pub fn to_linear_rgb(self) -> Self

pub fn to_cmyk(self) -> Self

pub fn to_hsl(self) -> Self

pub fn to_hsv(self) -> Self

Trait Implementations

impl Clone for Color

fn clone(&self) -> Color

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Color

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Alpha<Hsl, f32>> for Color

fn from(c: Hsl) -> Self

Converts to this type from the input type.

impl From<Alpha<Hsv, f32>> for Color

fn from(c: Hsv) -> Self

Converts to this type from the input type.

impl From<Alpha<Luma, f32>> for Color

fn from(c: Luma) -> Self

Converts to this type from the input type.

impl From<Alpha<Oklab, f32>> for Color

fn from(c: Oklab) -> Self

Converts to this type from the input type.

impl From<Alpha<Oklch, f32>> for Color

fn from(c: Oklch) -> Self

Converts to this type from the input type.

impl From<Alpha<Rgb<Linear<Srgb>>, f32>> for Color

fn from(c: LinearRgb) -> Self

Converts to this type from the input type.

impl From<Alpha<Rgb, f32>> for Color

fn from(c: Rgb) -> Self

Converts to this type from the input type.

impl From<Cmyk> for Color

fn from(c: Cmyk) -> Self

Converts to this type from the input type.

impl FromStr for Color

fn from_str(hex_str: &str) -> Result<Self, Self::Err>

Constructs a new color from hex strings like the following:

• #aef (shorthand, with leading hash),
• 7a03c2 (without alpha),
• abcdefff (with alpha).

The hash is optional and both lower and upper case are fine.

type Err = &'static str

The associated error which can be returned from parsing.

impl FromValue for Color

fn from_value(value: Value) -> HintedStrResult<Self>

Try to cast the value into an instance of Self.

impl Hash for Color

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for Color

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Color

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl NativeType for Color

const NAME: &'static str = "color"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq for Color

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Reflect for Color

fn input() -> CastInfo

Describe what can be cast into this value.

fn output() -> CastInfo

Describe what this value can be cast into.

fn castable(value: &Value) -> bool

Whether the given value can be converted to T.

fn error(found: &Value) -> HintedString

Produce an error message for an unacceptable value type.

impl Repr for Color

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Copy for Color

impl Eq for Color