Enum Gradient

pub enum Gradient {
    Linear(Arc<LinearGradient>),
    Radial(Arc<RadialGradient>),
    Conic(Arc<ConicGradient>),
}

A color gradient.

Typst supports linear gradients through the gradient.linear function, radial gradients through the gradient.radial function, and conic gradients through the gradient.conic function.

A gradient can be used for the following purposes:

• As a fill to paint the interior of a shape: {rect(fill: gradient.linear(..))}
• As a stroke to paint the outline of a shape: {rect(stroke: 1pt + gradient.linear(..))}
• As the fill of text: {set text(fill: gradient.linear(..))}
• As a color map you can sample from: {gradient.linear(..).sample(50%)}

Examples

>>> #set square(size: 50pt)
#stack(
  dir: ltr,
  spacing: 1fr,
  square(fill: gradient.linear(..color.map.rainbow)),
  square(fill: gradient.radial(..color.map.rainbow)),
  square(fill: gradient.conic(..color.map.rainbow)),
)

Gradients are also supported on text, but only when setting the relativeness to either {auto} (the default value) or {"parent"}. To create word-by-word or glyph-by-glyph gradients, you can wrap the words or characters of your text in boxes manually or through a show rule.

>>> #set page(width: auto, height: auto, margin: 12pt)
>>> #set text(size: 12pt)
#set text(fill: gradient.linear(red, blue))
#let rainbow(content) = {
  set text(fill: gradient.linear(..color.map.rainbow))
  box(content)
}

This is a gradient on text, but with a #rainbow[twist]!

Stops

A gradient is composed of a series of stops. Each of these stops has a color and an offset. The offset is a ratio between {0%} and {100%} or an angle between {0deg} and {360deg}. The offset is a relative position that determines how far along the gradient the stop is located. The stop’s color is the color of the gradient at that position. You can choose to omit the offsets when defining a gradient. In this case, Typst will space all stops evenly.

Relativeness

The location of the {0%} and {100%} stops depends on the dimensions of a container. This container can either be the shape that it is being painted on, or the closest surrounding container. This is controlled by the relative argument of a gradient constructor. By default, gradients are relative to the shape they are being painted on, unless the gradient is applied on text, in which case they are relative to the closest ancestor container.

Typst determines the ancestor container as follows:

• For shapes that are placed at the root/top level of the document, the closest ancestor is the page itself.
• For other shapes, the ancestor is the innermost [block] or [box] that contains the shape. This includes the boxes and blocks that are implicitly created by show rules and elements. For example, a [rotate] will not affect the parent of a gradient, but a [grid] will.

Color spaces and interpolation

Gradients can be interpolated in any color space. By default, gradients are interpolated in the Oklab color space, which is a perceptually uniform color space. This means that the gradient will be perceived as having a smooth progression of colors. This is particularly useful for data visualization.

However, you can choose to interpolate the gradient in any supported color space you want, but beware that some color spaces are not suitable for perceptually interpolating between colors. Consult the table below when choosing an interpolation space.

Color space	Perceptually uniform?
Oklab	Yes
Oklch	Yes
sRGB	No
linear-RGB	Yes
CMYK	No
Grayscale	Yes
HSL	No
HSV	No

>>> #set text(fill: white, font: "IBM Plex Sans", 8pt)
>>> #set block(spacing: 0pt)
#let spaces = (
  ("Oklab", color.oklab),
  ("Oklch", color.oklch),
  ("linear-RGB", color.linear-rgb),
  ("sRGB", color.rgb),
  ("CMYK", color.cmyk),
  ("HSL", color.hsl),
  ("HSV", color.hsv),
  ("Grayscale", color.luma),
)

#for (name, space) in spaces {
  block(
    width: 100%,
    inset: 4pt,
    fill: gradient.linear(
      red,
      blue,
      space: space,
    ),
    strong(upper(name)),
  )
}

Direction

Some gradients are sensitive to direction. For example, a linear gradient has an angle that determines its direction. Typst uses a clockwise angle, with 0° being from left to right, 90° from top to bottom, 180° from right to left, and 270° from bottom to top.

>>> #set square(size: 50pt)
#stack(
  dir: ltr,
  spacing: 1fr,
  square(fill: gradient.linear(red, blue, angle: 0deg)),
  square(fill: gradient.linear(red, blue, angle: 90deg)),
  square(fill: gradient.linear(red, blue, angle: 180deg)),
  square(fill: gradient.linear(red, blue, angle: 270deg)),
)

Presets

Typst predefines color maps that you can use with your gradients. See the color documentation for more details.

Note on file sizes

Gradients can be quite large, especially if they have many stops. This is because gradients are stored as a list of colors and offsets, which can take up a lot of space. If you are concerned about file sizes, you should consider the following:

• SVG gradients are currently inefficiently encoded. This will be improved in the future.
• PDF gradients in the color.oklab, color.hsv, color.hsl, and color.oklch color spaces are stored as a list of color.rgb colors with extra stops in between. This avoids needing to encode these color spaces in your PDF file, but it does add extra stops to your gradient, which can increase the file size.

Variants

Linear(Arc<LinearGradient>)

Radial(Arc<RadialGradient>)

Conic(Arc<ConicGradient>)

Implementations

impl Gradient

pub fn linear( args: &mut Args, span: Span, stops: Vec<Spanned<GradientStop>>, space: ColorSpace, relative: Smart<RelativeTo>, ) -> Result<Gradient, EcoVec<SourceDiagnostic>>

Creates a new linear gradient, in which colors transition along a straight line.

#rect(
  width: 100%,
  height: 20pt,
  fill: gradient.linear(
    ..color.map.viridis,
  ),
)

pub fn conic( span: Span, stops: Vec<Spanned<GradientStop>>, angle: Angle, space: ColorSpace, relative: Smart<RelativeTo>, center: Axes<Ratio>, ) -> Result<Gradient, EcoVec<SourceDiagnostic>>

Creates a new conic gradient, in which colors change radially around a center point.

You can control the center point of the gradient by using the center argument. By default, the center point is the center of the shape.

>>> #set circle(radius: 30pt)
#stack(
  dir: ltr,
  spacing: 1fr,
  circle(fill: gradient.conic(
    ..color.map.viridis,
  )),
  circle(fill: gradient.conic(
    ..color.map.viridis,
    center: (20%, 30%),
  )),
)

pub fn sharp( &self, steps: Spanned<usize>, smoothness: Spanned<Ratio>, ) -> Result<Gradient, EcoVec<SourceDiagnostic>>

Creates a sharp version of this gradient.

Sharp gradients have discrete jumps between colors, instead of a smooth transition. They are particularly useful for creating color lists for a preset gradient.

#set rect(width: 100%, height: 20pt)
#let grad = gradient.linear(..color.map.rainbow)
#rect(fill: grad)
#rect(fill: grad.sharp(5))
#rect(fill: grad.sharp(5, smoothness: 20%))

pub fn repeat( &self, repetitions: Spanned<usize>, mirror: bool, ) -> Result<Gradient, EcoVec<SourceDiagnostic>>

Repeats this gradient a given number of times, optionally mirroring it at each repetition.

#circle(
  radius: 40pt,
  fill: gradient
    .radial(aqua, white)
    .repeat(4),
)

pub fn kind(&self) -> Func

Returns the kind of this gradient.

pub fn stops(&self) -> Vec<GradientStop>

Returns the stops of this gradient.

pub fn space(&self) -> ColorSpace

Returns the mixing space of this gradient.

pub fn relative(&self) -> Smart<RelativeTo>

Returns the relative placement of this gradient.

pub fn angle(&self) -> Option<Angle>

Returns the angle of this gradient.

Returns {none} if the gradient is neither linear nor conic.

pub fn center(&self) -> Option<Axes<Ratio>>

Returns the center of this gradient.

Returns {none} if the gradient is neither radial nor conic.

pub fn radius(&self) -> Option<Ratio>

Returns the radius of this gradient.

Returns {none} if the gradient is not radial.

pub fn focal_center(&self) -> Option<Axes<Ratio>>

Returns the focal-center of this gradient.

Returns {none} if the gradient is not radial.

pub fn focal_radius(&self) -> Option<Ratio>

Returns the focal-radius of this gradient.

Returns {none} if the gradient is not radial.

pub fn sample(&self, t: RatioOrAngle) -> Color

Sample the gradient at a given position.

The position is either a position along the gradient (a [ratio] between {0%} and {100%}) or an [angle]. Any value outside of this range will be clamped.

pub fn samples(&self, ts: Vec<RatioOrAngle>) -> Array

Samples the gradient at multiple positions at once and returns the results as an array.

impl Gradient

pub fn with_relative(self, relative: RelativeTo) -> Gradient

Clones this gradient, but with a different relative placement.

pub fn stops_ref(&self) -> &[(Color, Ratio)]

Returns a reference to the stops of this gradient.

pub fn sample_at(&self, _: (f32, f32), _: (f32, f32)) -> Color

Samples the gradient at a given position, in the given container. Handles the aspect ratio and angle directly.

pub fn anti_alias(&self) -> bool

Does this gradient need to be anti-aliased?

pub fn unwrap_relative(&self, on_text: bool) -> RelativeTo

Returns the relative placement of this gradient, handling the special case of auto.

pub fn correct_aspect_ratio(angle: Angle, aspect_ratio: Ratio) -> Angle

Corrects this angle for the aspect ratio of a gradient.

This is used specifically for gradients.

Trait Implementations

impl Clone for Gradient

fn clone(&self) -> Gradient

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Gradient

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

Formats the value using the given formatter.

impl From<Gradient> for Paint

fn from(gradient: Gradient) -> Paint

Converts to this type from the input type.

impl FromValue for Gradient

fn from_value(value: Value) -> Result<Gradient, HintedString>

Try to cast the value into an instance of Self.

impl Hash for Gradient

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

where __H: Hasher,

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 Gradient

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Gradient

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 Gradient

const NAME: &'static str = "gradient"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq for Gradient

fn eq(&self, other: &Gradient) -> 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 Gradient

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 Gradient

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Eq for Gradient

impl StructuralPartialEq for Gradient