Docs for `theme()` missing some elements

[arcresu]

I noticed that the docs for theme() are missing the new palette.* elements.

That got me thinking that it would be possible to add a test to catch this in future, based on something like this:

all_elems <- names(ggplot2:::ggplot_global$element_tree)
doc_fmls <- rlang::fn_fmls_names(ggplot2::theme)
setdiff(all_elems, doc_fmls)
#>  [1] "strip.placement.x"            "strip.placement.y"           
#>  [3] "palette.colour.discrete"      "palette.colour.continuous"   
#>  [5] "palette.fill.discrete"        "palette.fill.continuous"     
#>  [7] "palette.alpha.discrete"       "palette.alpha.continuous"    
#>  [9] "palette.linewidth.discrete"   "palette.linewidth.continuous"
#> [11] "palette.size.discrete"        "palette.size.continuous"     
#> [13] "palette.shape.discrete"       "palette.shape.continuous"    
#> [15] "palette.linetype.discrete"    "palette.linetype.continuous"

^{Created on 2026-03-31 with reprex v2.1.1}

As discussed below, this issues is just about any missing parameters that were unintentionally left off.

[Anukool-pixel]

Hi,
I am interested in contributing to ggplot2 as part of GSoC 2026.

I would like to work on improving the documentation for theme() and fixing the missing elements mentioned here.
Please let me know if I can take this up or if there are any guidelines I should follow.

Thank you!

[arcresu]

Sorry @Anukool-pixel: I didn't notice your comment in time. I had already made some of the changes locally at the time of reporting the issue so I already went ahead and made a PR.

[teunbrand]

Hi sorry to jump on this only after you've already prepared a PR. The palette.* arguments in particular are intended to be hidden for users: they exist only so that extension developers have access to a 'parent' for theme inheritance purposes.

[arcresu]

No problem. I'm a little confused though - isn't it supported to set the default palette in the theme even if you're not making an extension? It's even one of the existing examples:

# You can also set default palettes in the theme
p4 + aes(colour = drat) +
  theme(palette.colour.continuous = c("white", "pink", "hotpink"))

I can understand not adding the sub theme helper, but not including them in the call prevents autocomplete in IDEs, makes them harder to discover etc.

[teunbrand]

Yeah maybe I didn't do a good job of explaining this. Yes it is supported to use settings like theme(palette.colour.continuous) but there isn't really a fixed set of the palette settings. Stuff like calc_element("palette.colour.continuous", complete_theme()) doesn't work as one would expect for example. I'd maybe have mull this over some more to consider if they maybe should become proper parts of themes.

[arcresu]

I understand that the palette elems might need some more thought. Were the strip placement ones also deliberately left out? If not I can reduce this PR to just dealing with those, and perhaps make the test into a snapshot analogous to the existing test for the sub theme setters?

[teunbrand]

I think documenting the strips are a good move. I don't know on top of my head just facet_wrap() or just facet_grid() also supports the more granular strip.text.y.left, strip.text.y.right, strip.text.x.top and strip.text.x.bottom, and if these that also applies to the strip.background (and if they do not apply, whether they should).

[arcresu]

The strip.text.* elements are only accessed directly within build_strip() which is called in render_strips() by each facet. As far as I can see that means both types of facets should support these options, but they're orthogonal to the strip placement which just chooses which of the possible strips to use. I think the existing docs are okay here.

[arcresu]

I've reduced the PR to not touch the palette elements and split off a new issue, so this is now just about the strip.placement.{x,y} and the test.