{"route":"/en-US-v0.13.1/reference/visualize/gradient/","title":"Gradient","description":"Documentation for the Gradient type.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"examples","name":"Examples","children":[]},{"id":"stops","name":"Stops","children":[]},{"id":"relativeness","name":"Relativeness","children":[]},{"id":"color-spaces-and-interpolation","name":"Color spaces and interpolation","children":[]},{"id":"direction","name":"Direction","children":[]},{"id":"presets","name":"Presets","children":[]},{"id":"note-on-file-sizes","name":"Note on file sizes","children":[]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-linear","name":"Linear Gradient","children":[{"id":"definitions-linear-stops","name":"stops","children":[]},{"id":"definitions-linear-space","name":"space","children":[]},{"id":"definitions-linear-relative","name":"relative","children":[]},{"id":"definitions-linear-dir","name":"dir","children":[]},{"id":"definitions-linear-angle","name":"angle","children":[]}]},{"id":"definitions-radial","name":"Radial","children":[{"id":"definitions-radial-stops","name":"stops","children":[]},{"id":"definitions-radial-space","name":"space","children":[]},{"id":"definitions-radial-relative","name":"relative","children":[]},{"id":"definitions-radial-center","name":"center","children":[]},{"id":"definitions-radial-radius","name":"radius","children":[]},{"id":"definitions-radial-focal-center","name":"focal-center","children":[]},{"id":"definitions-radial-focal-radius","name":"focal-radius","children":[]}]},{"id":"definitions-conic","name":"Conic","children":[{"id":"definitions-conic-stops","name":"stops","children":[]},{"id":"definitions-conic-angle","name":"angle","children":[]},{"id":"definitions-conic-space","name":"space","children":[]},{"id":"definitions-conic-relative","name":"relative","children":[]},{"id":"definitions-conic-center","name":"center","children":[]}]},{"id":"definitions-sharp","name":"Sharp","children":[{"id":"definitions-sharp-steps","name":"steps","children":[]},{"id":"definitions-sharp-smoothness","name":"smoothness","children":[]}]},{"id":"definitions-repeat","name":"Repeat","children":[{"id":"definitions-repeat-repetitions","name":"repetitions","children":[]},{"id":"definitions-repeat-mirror","name":"mirror","children":[]}]},{"id":"definitions-kind","name":"Kind","children":[]},{"id":"definitions-stops","name":"Stops","children":[]},{"id":"definitions-space","name":"Space","children":[]},{"id":"definitions-relative","name":"Relative","children":[]},{"id":"definitions-angle","name":"Angle","children":[]},{"id":"definitions-center","name":"Center","children":[]},{"id":"definitions-radius","name":"Radius","children":[]},{"id":"definitions-focal-center","name":"Focal Center","children":[]},{"id":"definitions-focal-radius","name":"Focal Radius","children":[]},{"id":"definitions-sample","name":"Sample","children":[{"id":"definitions-sample-t","name":"t","children":[]}]},{"id":"definitions-samples","name":"Samples","children":[{"id":"definitions-samples-ts","name":"ts","children":[]}]}]}],"body":{"kind":"type","content":{"name":"gradient","title":"Gradient","keywords":[],"oneliner":"A color gradient.","details":"

A color gradient.

\n

Typst supports linear gradients through the\ngradient.linear function, radial gradients through\nthe gradient.radial function, and conic gradients\nthrough the gradient.conic function.

\n

A gradient can be used for the following purposes:

\n\n

Examples

\n
#stack(\n  dir: ltr,\n  spacing: 1fr,\n  square(fill: gradient.linear(..color.map.rainbow)),\n  square(fill: gradient.radial(..color.map.rainbow)),\n  square(fill: gradient.conic(..color.map.rainbow)),\n)\n
\"Preview\"
\n

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

\n
#set text(fill: gradient.linear(red, blue))\n#let rainbow(content) = {\n  set text(fill: gradient.linear(..color.map.rainbow))\n  box(content)\n}\n\nThis is a gradient on text, but with a #rainbow[twist]!\n
\"Preview\"
\n

Stops

\n

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

\n

Relativeness

\n

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

\n

Typst determines the ancestor container as follows:

\n\n

Color spaces and interpolation

\n

Gradients can be interpolated in any color space. By default, gradients are\ninterpolated in the Oklab color space, which is a\nperceptually uniform\ncolor space. This means that the gradient will be perceived as having a\nsmooth progression of colors. This is particularly useful for data\nvisualization.

\n

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

\n\n\n\n\n\n\n\n\n\n
Color spacePerceptually uniform?
OklabYes
OklchYes
sRGBNo
linear-RGBYes
CMYKNo
GrayscaleYes
HSLNo
HSVNo
\n
\"Preview\"
\n

Direction

\n

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

\n
#stack(\n  dir: ltr,\n  spacing: 1fr,\n  square(fill: gradient.linear(red, blue, angle: 0deg)),\n  square(fill: gradient.linear(red, blue, angle: 90deg)),\n  square(fill: gradient.linear(red, blue, angle: 180deg)),\n  square(fill: gradient.linear(red, blue, angle: 270deg)),\n)\n
\"Preview\"
\n

Presets

\n

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

\n

Note on file sizes

\n

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

\n","constructor":null,"scope":[{"path":["gradient"],"name":"linear","title":"Linear Gradient","keywords":[],"oneliner":"Creates a new linear gradient, in which colors transition along a","element":false,"contextual":false,"deprecation":null,"details":"

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

","example":"
#rect(\n  width: 100%,\n  height: 20pt,\n  fill: gradient.linear(\n    ..color.map.viridis,\n  ),\n)\n
\"Preview\"
","self":false,"params":[{"name":"stops","details":"

The color stops of the gradient.

","example":null,"types":["color","array"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false},{"name":"space","details":"

The color space in which to interpolate the gradient.

\n

Defaults to a perceptually uniform color space called\nOklab.

","example":null,"types":["any"],"strings":[],"default":"oklab","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"relative","details":"

The relative placement of the gradient.

\n

For an element placed at the root/top level of the document, the\nparent is the page itself. For other elements, the parent is the\ninnermost block, box, column, grid, or stack that contains the\nelement.

","example":null,"types":["auto","str"],"strings":[{"string":"self","details":"

The gradient is relative to itself (its own bounding box).

"},{"string":"parent","details":"

The gradient is relative to its parent (the parent's bounding box).

"}],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"dir","details":"

The direction of the gradient.

","example":null,"types":["direction"],"strings":[],"default":"ltr","positional":true,"named":false,"required":false,"variadic":false,"settable":false},{"name":"angle","details":"

The angle of the gradient.

","example":null,"types":["angle"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["gradient"],"scope":[]},{"path":["gradient"],"name":"radial","title":"Radial","keywords":[],"oneliner":"Creates a new radial gradient, in which colors radiate away from an","element":false,"contextual":false,"deprecation":null,"details":"

Creates a new radial gradient, in which colors radiate away from an\norigin.

\n

The gradient is defined by two circles: the focal circle and the end\ncircle. The focal circle is a circle with center focal-center and\nradius focal-radius, that defines the points at which the gradient\nstarts and has the color of the first stop. The end circle is a circle\nwith center center and radius radius, that defines the points at\nwhich the gradient ends and has the color of the last stop. The gradient\nis then interpolated between these two circles.

\n

Using these four values, also called the focal point for the starting\ncircle and the center and radius for the end circle, we can define a\ngradient with more interesting properties than a basic radial gradient.

","example":"
#stack(\n  dir: ltr,\n  spacing: 1fr,\n  circle(fill: gradient.radial(\n    ..color.map.viridis,\n  )),\n  circle(fill: gradient.radial(\n    ..color.map.viridis,\n    focal-center: (10%, 40%),\n    focal-radius: 5%,\n  )),\n)\n
\"Preview\"
","self":false,"params":[{"name":"stops","details":"

The color stops of the gradient.

","example":null,"types":["color","array"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false},{"name":"space","details":"

The color space in which to interpolate the gradient.

\n

Defaults to a perceptually uniform color space called\nOklab.

","example":null,"types":["any"],"strings":[],"default":"oklab","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"relative","details":"

The relative placement of the gradient.

\n

For an element placed at the root/top level of the document, the parent\nis the page itself. For other elements, the parent is the innermost block,\nbox, column, grid, or stack that contains the element.

","example":null,"types":["auto","str"],"strings":[{"string":"self","details":"

The gradient is relative to itself (its own bounding box).

"},{"string":"parent","details":"

The gradient is relative to its parent (the parent's bounding box).

"}],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"center","details":"

The center of the end circle of the gradient.

\n

A value of (50%, 50%) means that the end circle is\ncentered inside of its container.

","example":null,"types":["array"],"strings":[],"default":"(50%, 50%)","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"radius","details":"

The radius of the end circle of the gradient.

\n

By default, it is set to 50%. The ending radius must be bigger\nthan the focal radius.

","example":null,"types":["ratio"],"strings":[],"default":"50%","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"focal-center","details":"

The center of the focal circle of the gradient.

\n

The focal center must be inside of the end circle.

\n

A value of (50%, 50%) means that the focal circle is\ncentered inside of its container.

\n

By default it is set to the same as the center of the last circle.

","example":null,"types":["auto","array"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"focal-radius","details":"

The radius of the focal circle of the gradient.

\n

The focal center must be inside of the end circle.

\n

By default, it is set to 0%. The focal radius must be smaller\nthan the ending radius`.

","example":null,"types":["ratio"],"strings":[],"default":"0%","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["gradient"],"scope":[]},{"path":["gradient"],"name":"conic","title":"Conic","keywords":[],"oneliner":"Creates a new conic gradient, in which colors change radially around a","element":false,"contextual":false,"deprecation":null,"details":"

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

\n

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

","example":"
#stack(\n  dir: ltr,\n  spacing: 1fr,\n  circle(fill: gradient.conic(\n    ..color.map.viridis,\n  )),\n  circle(fill: gradient.conic(\n    ..color.map.viridis,\n    center: (20%, 30%),\n  )),\n)\n
\"Preview\"
","self":false,"params":[{"name":"stops","details":"

The color stops of the gradient.

","example":null,"types":["color","array"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false},{"name":"angle","details":"

The angle of the gradient.

","example":null,"types":["angle"],"strings":[],"default":"0deg","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"space","details":"

The color space in which to interpolate the gradient.

\n

Defaults to a perceptually uniform color space called\nOklab.

","example":null,"types":["any"],"strings":[],"default":"oklab","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"relative","details":"

The relative placement of the gradient.

\n

For an element placed at the root/top level of the document, the parent\nis the page itself. For other elements, the parent is the innermost block,\nbox, column, grid, or stack that contains the element.

","example":null,"types":["auto","str"],"strings":[{"string":"self","details":"

The gradient is relative to itself (its own bounding box).

"},{"string":"parent","details":"

The gradient is relative to its parent (the parent's bounding box).

"}],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"center","details":"

The center of the last circle of the gradient.

\n

A value of (50%, 50%) means that the end circle is\ncentered inside of its container.

","example":null,"types":["array"],"strings":[],"default":"(50%, 50%)","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["gradient"],"scope":[]},{"path":["gradient"],"name":"sharp","title":"Sharp","keywords":[],"oneliner":"Creates a sharp version of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Creates a sharp version of this gradient.

\n

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

","example":"
#set rect(width: 100%, height: 20pt)\n#let grad = gradient.linear(..color.map.rainbow)\n#rect(fill: grad)\n#rect(fill: grad.sharp(5))\n#rect(fill: grad.sharp(5, smoothness: 20%))\n
\"Preview\"
","self":true,"params":[{"name":"steps","details":"

The number of stops in the gradient.

","example":null,"types":["int"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"smoothness","details":"

How much to smooth the gradient.

","example":null,"types":["ratio"],"strings":[],"default":"0%","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["gradient"],"scope":[]},{"path":["gradient"],"name":"repeat","title":"Repeat","keywords":[],"oneliner":"Repeats this gradient a given number of times, optionally mirroring it","element":false,"contextual":false,"deprecation":null,"details":"

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

","example":"
#circle(\n  radius: 40pt,\n  fill: gradient\n    .radial(aqua, white)\n    .repeat(4),\n)\n
\"Preview\"
","self":true,"params":[{"name":"repetitions","details":"

The number of times to repeat the gradient.

","example":null,"types":["int"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"mirror","details":"

Whether to mirror the gradient at each repetition.

","example":null,"types":["bool"],"strings":[],"default":"false","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["gradient"],"scope":[]},{"path":["gradient"],"name":"kind","title":"Kind","keywords":[],"oneliner":"Returns the kind of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the kind of this gradient.

","example":null,"self":true,"params":[],"returns":["function"],"scope":[]},{"path":["gradient"],"name":"stops","title":"Stops","keywords":[],"oneliner":"Returns the stops of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the stops of this gradient.

","example":null,"self":true,"params":[],"returns":["array"],"scope":[]},{"path":["gradient"],"name":"space","title":"Space","keywords":[],"oneliner":"Returns the mixing space of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the mixing space of this gradient.

","example":null,"self":true,"params":[],"returns":["any"],"scope":[]},{"path":["gradient"],"name":"relative","title":"Relative","keywords":[],"oneliner":"Returns the relative placement of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the relative placement of this gradient.

","example":null,"self":true,"params":[],"returns":["auto","str"],"scope":[]},{"path":["gradient"],"name":"angle","title":"Angle","keywords":[],"oneliner":"Returns the angle of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the angle of this gradient.

\n

Returns none if the gradient is neither linear nor conic.

","example":null,"self":true,"params":[],"returns":["none","angle"],"scope":[]},{"path":["gradient"],"name":"center","title":"Center","keywords":[],"oneliner":"Returns the center of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the center of this gradient.

\n

Returns none if the gradient is neither radial nor conic.

","example":null,"self":true,"params":[],"returns":["none","array"],"scope":[]},{"path":["gradient"],"name":"radius","title":"Radius","keywords":[],"oneliner":"Returns the radius of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the radius of this gradient.

\n

Returns none if the gradient is not radial.

","example":null,"self":true,"params":[],"returns":["none","ratio"],"scope":[]},{"path":["gradient"],"name":"focal-center","title":"Focal Center","keywords":[],"oneliner":"Returns the focal-center of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the focal-center of this gradient.

\n

Returns none if the gradient is not radial.

","example":null,"self":true,"params":[],"returns":["none","array"],"scope":[]},{"path":["gradient"],"name":"focal-radius","title":"Focal Radius","keywords":[],"oneliner":"Returns the focal-radius of this gradient.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the focal-radius of this gradient.

\n

Returns none if the gradient is not radial.

","example":null,"self":true,"params":[],"returns":["none","ratio"],"scope":[]},{"path":["gradient"],"name":"sample","title":"Sample","keywords":[],"oneliner":"Sample the gradient at a given position.","element":false,"contextual":false,"deprecation":null,"details":"

Sample the gradient at a given position.

\n

The position is either a position along the gradient (a ratio between\n0% and 100%) or an angle. Any value outside of this range will\nbe clamped.

","example":null,"self":true,"params":[{"name":"t","details":"

The position at which to sample the gradient.

","example":null,"types":["angle","ratio"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["color"],"scope":[]},{"path":["gradient"],"name":"samples","title":"Samples","keywords":[],"oneliner":"Samples the gradient at multiple positions at once and returns the","element":false,"contextual":false,"deprecation":null,"details":"

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

","example":null,"self":true,"params":[{"name":"ts","details":"

The positions at which to sample the gradient.

","example":null,"types":["angle","ratio"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false}],"returns":["array"],"scope":[]}]}}}