Injecting Custom Strings in gridcetz Figures

This vignette demonstrates three strategies for injecting custom strings into Typst figures exported with gridcetz. These approaches allow you to add annotations, labels, or other custom content to your figures, either directly or in a robust, reusable way.

1. Simple: Inline `#show` in Header or Parent Document

The most straightforward way to inject a custom string is to use Typst’s #show directive in the header of your exported .typ file, or in the parent document that includes it.

#show my-label: "This is anything I want"

Then, in your figure code, reference my-label:

content((2.54, 1.27), anchor: "center", [my-label])

This will display your custom string wherever my-label is used.

Add wrapper creation, Typst compilation, and SVG display for the simple #show strategy.

g <- textGrob("∂mycustomlabel")
outfile1 <- file.path(fig_dir, "figure1.typ")
gridcetz(
  filename = outfile1,
  width = 2,
  height = 1,
  header = '#import "@preview/cetz:0.4.2" as cetz',
  expr = { grid::grid.draw(g) }
)
outfile1

## [1] "figures/injecting-custom-strings/figure1.typ"

Typst wrapper (wrapper1.typ):

#show "∂mycustomlabel": text(fill: gradient.linear(..color.map.rainbow))[$alpha = beta$]
#include "<path-to-outfile1>"

## [1] "figures/injecting-custom-strings/wrapper1.svg"

2. Using `metadata` for Scoped Injection

In your exported figure, add a metadata tag:

#metadata("")<someweirdlabel>
content((2.54, 1.27), anchor: "center", [<someweirdlabel>])

Then, in the parent document, define the label with #show:

g2 <- textGrob(r"(#metadata(none)<mycustomlabel2>)")
outfile2 <- file.path(fig_dir, "figure2.typ")
gridcetz(
  filename = outfile2,
  width = 2,
  height = 1,
  header = '#import "@preview/cetz:0.4.2" as cetz\n',
  expr = { grid::grid.draw(g2) }
)
outfile2

## [1] "figures/injecting-custom-strings/figure2.typ"

Typst wrapper (wrapper2.typ):

#show <mycustomlabel2>: text(fill: gradient.linear(..color.map.rainbow))[$alpha = beta$]
#include "<path-to-outfile2>"

This allows the parent document to control the label without modifying the figure code.

## [1] "figures/injecting-custom-strings/wrapper2.svg"

3. Robust: Wrapping Output as a Typst Function (Custom Header/Footer)

For maximum flexibility and reusability, you can wrap the exported figure as a Typst function using a custom header and footer in gridcetz. This lets you pass any string as a parameter.

Custom header:

#import "@preview/cetz:0.4.2" as cetz
#import cetz.draw: *

#let my-plot(custom-label) = {[

Custom footer:

])

Export with gridcetz:

outfile3 <- file.path(fig_dir, "figure3.typ")
gridcetz(
  filename = outfile3,
  width = 2,
  height = 1,
  header = '#import "@preview/cetz:0.4.2" as cetz\n#import cetz.draw: *\n\n#let my-plot(custom-label) = {[',
  footer = ']}',
  expr = {
    grid::grid.draw(textGrob(r"(#custom-label)"))
  }
)
outfile3

## [1] "figures/injecting-custom-strings/figure3.typ"

## [1] "figures/injecting-custom-strings/wrapper3.svg"

Header used:

#import "@preview/cetz:0.4.2" as cetz
#import cetz.draw: *

#let my-plot(custom-label) = {[

Footer used:

])

Typst wrapper (wrapper3.typ):

#import "<path-to-outfile3>": my-plot
#my-plot(text(fill: gradient.linear(..color.map.rainbow))[$alpha = beta$])

gridcetz(
  filename = "myplot.typ",
  header = '...header above...',
  footer = '...footer above...'
)

Usage in Typst:

#my-plot(text(fill: gradient.linear(..color.map.rainbow))[$alpha = beta$])

This approach ensures your figure is fully encapsulated and reusable with any label or content you wish to inject.

For more details, see the other articles and vignettes in this package.

Injecting Custom Strings in gridcetz Figures