Documentation

figureElement
Question mark

A figure with an optional caption.

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

Examples

The example below shows a basic figure with an image:

@glacier shows a glacier. Glaciers
are complex systems.

#figure(
  image("glacier.jpg", width: 80%),
  caption: [A curious figure.],
) <glacier>
Preview

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

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

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

Figure behaviour

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

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

#show figure: set block(breakable: true)

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

Caption customization

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

#show figure.caption: emph

#figure(
  rect[Hello],
  caption: [I am emphasized!],
)
Preview

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

#show figure.where(
  kind: table
): set figure.caption(position: top)

#figure(
  table(columns: 2)[A][B][C][D],
  caption: [I'm up here],
)
Preview

Parameters
Question mark

body
content
RequiredPositional
Question mark

The content of the figure. Often, an image.

placement
none or auto or alignment
Settable
Question mark

The figure's placement on the page.

The gap between the main flow content and the floating figure is controlled by the clearance argument on the place function.

Default: none

View example
#set page(height: 200pt)

= Introduction
#figure(
  placement: bottom,
  caption: [A glacier],
  image("glacier.jpg", width: 60%),
)
#lorem(60)
Preview Preview

scope
str
Settable
Question mark

Relative to which containing scope the figure is placed.

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

Has no effect if placement is none.

VariantDetails
"column"

Place into the current column.

"parent"

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

Default: "column"

View example
#set page(height: 250pt, columns: 2)

= Introduction
#figure(
  placement: bottom,
  scope: "parent",
  caption: [A glacier],
  image("glacier.jpg", width: 60%),
)
#lorem(60)
Preview Preview

caption
none or content
Settable
Question mark

The figure's caption.

Default: none

kind
auto or str or function
Settable
Question mark

The kind of figure this is.

All figures of the same kind share a common counter.

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

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

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

Default: auto

View example
#figure(
  circle(radius: 10pt),
  caption: [A curious atom.],
  kind: "atom",
  supplement: [Atom],
)
Preview

supplement
none or auto or content or function
Settable
Question mark

The figure's supplement.

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

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

Default: auto

View example
#figure(
  [The contents of my figure!],
  caption: [My custom figure],
  supplement: [Bar],
  kind: "foo",
)
Preview

numbering
none or str or function
Settable
Question mark

How to number the figure. Accepts a numbering pattern or function.

Default: "1"

gap
length
Settable
Question mark

The vertical gap between the body and caption.

Default: 0.65em

outlined
bool
Settable
Question mark

Whether the figure should appear in an outline of figures.

Default: true

Definitions
Question mark

captionElement
Question mark

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

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

#show figure.caption: emph

#figure(
  rect[Hello],
  caption: [A rectangle],
)
Preview

position
alignment
Settable
Question mark

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

Default: bottom

View example
#show figure.where(
  kind: table
): set figure.caption(position: top)

#figure(
  table(columns: 2)[A][B],
  caption: [I'm up here],
)

#figure(
  rect[Hi],
  caption: [I'm down here],
)

#figure(
  table(columns: 2)[A][B],
  caption: figure.caption(
    position: bottom,
    [I'm down here too!]
  )
)
Preview

separator
auto or content
Settable
Question mark

The separator which will appear between the number and body.

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

Default: auto

View example
#set figure.caption(separator: [ --- ])

#figure(
  rect[Hello],
  caption: [A rectangle],
)
Preview

body
content
RequiredPositional
Question mark

The caption's body.

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

View example
#show figure.caption: it => [
  #underline(it.body) |
  #it.supplement
  #context it.counter.display(it.numbering)
]

#figure(
  rect[Hello],
  caption: [A rectangle],
)
Preview