{"route":"/en-US-v0.13.1/reference/model/figure/","title":"Figure","description":"Documentation for the `figure` function.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"examples","name":"Examples","children":[]},{"id":"figure-behaviour","name":"Figure behaviour","children":[]},{"id":"caption-customization","name":"Caption customization","children":[]},{"id":"parameters","name":"Parameters","children":[{"id":"parameters-body","name":"body","children":[]},{"id":"parameters-placement","name":"placement","children":[]},{"id":"parameters-scope","name":"scope","children":[]},{"id":"parameters-caption","name":"caption","children":[]},{"id":"parameters-kind","name":"kind","children":[]},{"id":"parameters-supplement","name":"supplement","children":[]},{"id":"parameters-numbering","name":"numbering","children":[]},{"id":"parameters-gap","name":"gap","children":[]},{"id":"parameters-outlined","name":"outlined","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-caption","name":"Caption","children":[{"id":"definitions-caption-position","name":"position","children":[]},{"id":"definitions-caption-separator","name":"separator","children":[]},{"id":"definitions-caption-body","name":"body","children":[]}]}]}],"body":{"kind":"func","content":{"path":[],"name":"figure","title":"Figure","keywords":[],"oneliner":"A figure with an optional caption.","element":true,"contextual":false,"deprecation":null,"details":"

A figure with an optional caption.

\n

Automatically detects its kind to select the correct counting track. For\nexample, figures containing images will be numbered separately from figures\ncontaining tables.

\n

Examples

\n

The example below shows a basic figure with an image:

\n
@glacier shows a glacier. Glaciers\nare complex systems.\n\n#figure(\n  image("glacier.jpg", width: 80%),\n  caption: [A curious figure.],\n) <glacier>\n
\"Preview\"
\n

You can also insert tables into figures to give them a caption.\nThe figure will detect this and automatically use a separate counter.

\n
#figure(\n  table(\n    columns: 4,\n    [t], [1], [2], [3],\n    [y], [0.3s], [0.4s], [0.8s],\n  ),\n  caption: [Timing results],\n)\n
\"Preview\"
\n

This behaviour can be overridden by explicitly specifying the figure's\nkind. All figures of the same kind share a common counter.

\n

Figure behaviour

\n

By default, figures are placed within the flow of content. To make them\nfloat to the top or bottom of the page, you can use the\nplacement argument.

\n

If your figure is too large and its contents are breakable across pages\n(e.g. if it contains a large table), then you can make the figure itself\nbreakable across pages as well with this show rule:

\n
#show figure: set block(breakable: true)\n
\n

See the block documentation for more information about\nbreakable and non-breakable blocks.

\n

Caption customization

\n

You can modify the appearance of the figure's caption with its associated\ncaption function. In the example below, we emphasize\nall captions:

\n
#show figure.caption: emph\n\n#figure(\n  rect[Hello],\n  caption: [I am emphasized!],\n)\n
\"Preview\"
\n

By using a where selector, we can scope such rules to\nspecific kinds of figures. For example, to position the caption above\ntables, but keep it below for all other kinds of figures, we could write the\nfollowing show-set rule:

\n
#show figure.where(\n  kind: table\n): set figure.caption(position: top)\n\n#figure(\n  table(columns: 2)[A][B][C][D],\n  caption: [I'm up here],\n)\n
\"Preview\"
","example":null,"self":false,"params":[{"name":"body","details":"

The content of the figure. Often, an image.

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

The figure's placement on the page.

\n\n

The gap between the main flow content and the floating figure is\ncontrolled by the clearance argument on the\nplace function.

","example":"
#set page(height: 200pt)\n\n= Introduction\n#figure(\n  placement: bottom,\n  caption: [A glacier],\n  image("glacier.jpg", width: 60%),\n)\n#lorem(60)\n
\"Preview\"
","types":["none","auto","alignment"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"scope","details":"

Relative to which containing scope the figure is placed.

\n

Set this to "parent" to create a full-width figure in a two-column\ndocument.

\n

Has no effect if placement is none.

","example":"
#set page(height: 250pt, columns: 2)\n\n= Introduction\n#figure(\n  placement: bottom,\n  scope: "parent",\n  caption: [A glacier],\n  image("glacier.jpg", width: 60%),\n)\n#lorem(60)\n
\"Preview\"
","types":["str"],"strings":[{"string":"column","details":"

Place into the current column.

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

Place relative to the parent, letting the content span over all columns.

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

The figure's caption.

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

The kind of figure this is.

\n

All figures of the same kind share a common counter.

\n

If set to auto, the figure will try to automatically determine its\nkind based on the type of its body. Automatically detected kinds are\ntables and code. In other cases, the inferred kind is\nthat of an image.

\n

Setting this to something other than auto will override the\nautomatic detection. This can be useful if

\n\n

You can set the kind to be an element function or a string. If you set\nit to an element function other than table, raw\nor image, you will need to manually specify the figure's\nsupplement.

","example":"
#figure(\n  circle(radius: 10pt),\n  caption: [A curious atom.],\n  kind: "atom",\n  supplement: [Atom],\n)\n
\"Preview\"
","types":["auto","str","function"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"supplement","details":"

The figure's supplement.

\n

If set to auto, the figure will try to automatically determine the\ncorrect supplement based on the kind and the active\ntext language. If you are using a custom figure type, you\nwill need to manually specify the supplement.

\n

If a function is specified, it is passed the first descendant of the\nspecified kind (typically, the figure's body) and should return\ncontent.

","example":"
#figure(\n  [The contents of my figure!],\n  caption: [My custom figure],\n  supplement: [Bar],\n  kind: "foo",\n)\n
\"Preview\"
","types":["none","auto","content","function"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"numbering","details":"

How to number the figure. Accepts a\nnumbering pattern or function.

","example":null,"types":["none","str","function"],"strings":[],"default":""1"","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"gap","details":"

The vertical gap between the body and caption.

","example":null,"types":["length"],"strings":[],"default":"0.65em","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"outlined","details":"

Whether the figure should appear in an outline of figures.

","example":null,"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[{"path":["figure"],"name":"caption","title":"Caption","keywords":[],"oneliner":"The caption of a figure. This element can be used in set and show rules to","element":true,"contextual":false,"deprecation":null,"details":"

The caption of a figure. This element can be used in set and show rules to\ncustomize the appearance of captions for all figures or figures of a\nspecific kind.

\n

In addition to its pos and body, the caption also provides the\nfigure's kind, supplement, counter, and numbering as fields. These\nparts can be used in where selectors and show rules to\nbuild a completely custom caption.

","example":"
#show figure.caption: emph\n\n#figure(\n  rect[Hello],\n  caption: [A rectangle],\n)\n
\"Preview\"
","self":false,"params":[{"name":"position","details":"

The caption's position in the figure. Either top or bottom.

","example":"
#show figure.where(\n  kind: table\n): set figure.caption(position: top)\n\n#figure(\n  table(columns: 2)[A][B],\n  caption: [I'm up here],\n)\n\n#figure(\n  rect[Hi],\n  caption: [I'm down here],\n)\n\n#figure(\n  table(columns: 2)[A][B],\n  caption: figure.caption(\n    position: bottom,\n    [I'm down here too!]\n  )\n)\n
\"Preview\"
","types":["alignment"],"strings":[],"default":"bottom","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"separator","details":"

The separator which will appear between the number and body.

\n

If set to auto, the separator will be adapted to the current\nlanguage and region.

","example":"
#set figure.caption(separator: [ --- ])\n\n#figure(\n  rect[Hello],\n  caption: [A rectangle],\n)\n
\"Preview\"
","types":["auto","content"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"body","details":"

The caption's body.

\n

Can be used alongside kind, supplement, counter, numbering, and\nlocation to completely customize the caption.

","example":"
#show figure.caption: it => [\n  #underline(it.body) |\n  #it.supplement\n  #context it.counter.display(it.numbering)\n]\n\n#figure(\n  rect[Hello],\n  caption: [A rectangle],\n)\n
\"Preview\"
","types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["content"],"scope":[]}]}}}