`tab_spanner()` unnecessarily reorders columns when `gather = TRUE`

[rossellhayes]

Prework

• Read and agree to the code of conduct and contributing guidelines.
• If there is already a relevant issue, whether open or closed, comment on the existing thread instead of posting a new issue.

Description

When calling tab_spanner() with the gather = TRUE argument, columns are reordered to match the order they were specified in the columns argument. They do not maintain their existing order in the table.

Reproducible example

library(gt)

data.frame(a = 1, b = 2, c = 3) |> 
  gt()

a	b	c
1	2	3

Adding a tab_spanner() with gather = TRUE (the default) reorders the columns.

data.frame(a = 1, b = 2, c = 3) |> 
  gt() |> 
  tab_spanner("Spanner", columns = c(c, b), gather = TRUE)

a	Spanner
	c	b
1	3	2

Compare with gather = FALSE, where columns preserve their existing order even though they are specified out of order in the columns argument.

data.frame(a = 1, b = 2, c = 3) |> 
  gt() |> 
  tab_spanner("Spanner", columns = c(c, b), gather = FALSE)

a	Spanner
	b	c
1	2	3

^{Created on 2025-11-17 with reprex v2.1.1}

Expected result

I believe that the columns should have stayed in the order the appeared in the original table, based on this text from the ?tab_spanner help file:

gather
Gather columns together⁠
scalar<logical> // default: TRUE
An option to move the specified columns such that they are unified under the spanner. Ordering of the moved-into-place columns will be preserved in all cases. By default, this is set to TRUE.

This suggests to me that when gather = TRUE, columns may be moved so that all items covered by the tab_spanner() are adjacent, but their order should be the same as before they were moved. In the case in the reprex above, the order of columns changed even though no column needed to be moved to make all spanned columns adjacent.

In the toy example above, the solution is obvious: one can simply reorder the columns argument. But this becomes more complicated if e.g. using multiple tidyselect helpers.

Given this, I think either

• the tab_spanner() function should be refactored to ensure that the relative order of gathered columns are preserved, or
• if this is intended behavior, the help file for tab_spanner() should be edited to make this clear.

Session info

Session info

sessioninfo::session_info()
#> ─ Session info ───────────────────────────────────────────────────────────────
#>  setting  value
#>  version  R version 4.5.1 (2025-06-13)
#>  os       macOS Sequoia 15.6.1
#>  system   aarch64, darwin20
#>  ui       X11
#>  language (EN)
#>  collate  en_US.UTF-8
#>  ctype    en_US.UTF-8
#>  tz       America/New_York
#>  date     2025-11-17
#>  pandoc   3.6.3 @ /Applications/RStudio.app/Contents/Resources/app/quarto/bin/tools/aarch64/ (via rmarkdown)
#>  quarto   1.7.30 @ /usr/local/bin/quarto
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────
#>  package     * version date (UTC) lib source
#>  cli           3.6.5   2025-04-23 [1] RSPM
#>  digest        0.6.37  2024-08-19 [1] RSPM
#>  dplyr         1.1.4   2023-11-17 [1] RSPM
#>  evaluate      1.0.5   2025-08-27 [1] RSPM
#>  fastmap       1.2.0   2024-05-15 [1] RSPM
#>  fs            1.6.6   2025-04-12 [1] RSPM
#>  generics      0.1.4   2025-05-09 [1] RSPM
#>  glue          1.8.0   2024-09-30 [1] RSPM
#>  gt          * 1.1.0   2025-09-23 [1] RSPM
#>  htmltools     0.5.8.1 2024-04-04 [1] RSPM
#>  knitr         1.50    2025-03-16 [1] RSPM
#>  lifecycle     1.0.4   2023-11-07 [1] RSPM
#>  magrittr      2.0.4   2025-09-12 [1] CRAN (R 4.5.0)
#>  pillar        1.11.1  2025-09-17 [1] RSPM
#>  pkgconfig     2.0.3   2019-09-22 [1] RSPM
#>  R6            2.6.1   2025-02-15 [1] RSPM
#>  reprex        2.1.1   2024-07-06 [2] RSPM
#>  rlang         1.1.6   2025-04-11 [1] RSPM
#>  rmarkdown     2.29    2024-11-04 [1] RSPM
#>  rstudioapi    0.17.1  2024-10-22 [1] RSPM
#>  sessioninfo   1.2.3   2025-02-05 [2] RSPM
#>  tibble        3.3.0   2025-06-08 [1] RSPM
#>  tidyselect    1.2.1   2024-03-11 [1] RSPM
#>  vctrs         0.6.5   2023-12-01 [1] RSPM
#>  withr         3.0.2   2024-10-28 [1] RSPM
#>  xfun          0.53    2025-08-19 [1] RSPM
#>  xml2          1.4.0   2025-08-20 [1] RSPM
#>  yaml          2.3.10  2024-07-26 [1] RSPM
#> 
#>  [1] /Users/alex/Library/R/arm64/4.5/library
#>  [2] /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/library
#>  * ── Packages attached to the search path.
#> 
#> ──────────────────────────────────────────────────────────────────────────────

[rich-iannone]

Thanks for filing this issue! It's definitely not the intended behavior (original column order should always be preserved). Will fix this shortly.