gt() table placement in LaTeX / PDF output doesn't work as expected

[mine-cetinkaya-rundel]

Description

gt() tables in Quarto documents with format: pdf are not placed where they should be in the output.

Reproducible example

---
title: "Title"
format: pdf
keep-tex: true
execute:
  echo: fenced
---

```{r}
library(knitr)
library(gt)
```

# Section 1

The `gt()` table is at the bottom of the page but it should be immediately below this text.

```{r}
gt(mtcars[1:5,1:5])
```

This text should be below the table.

{{< pagebreak >}}

# Section 2

The `gt()` should be below this text, but it's showing up above it.

```{r}
gt(mtcars[1:10,1:5])
```

{{< pagebreak >}}

# Section 3

The `kable()` table is correctly showing up below this text.

```{r}
kable(mtcars[10:20,1:5])
```

Rendered output is below.

Untitled-1.pdf

Expected result

The reprex above includes the expected results in each case as well.

Session info

R version 4.5.0 (2025-04-11)
Platform: aarch64-apple-darwin20
Running under: macOS Sequoia 15.5

Matrix products: default
BLAS:   /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libBLAS.dylib 
LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

time zone: America/New_York
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
 [1] palmerpenguins_0.1.1 lubridate_1.9.4      forcats_1.0.0        stringr_1.5.1       
 [5] dplyr_1.1.4          purrr_1.0.4          readr_2.1.5          tidyr_1.3.1         
 [9] tibble_3.3.0.9000    ggplot2_3.5.2        tidyverse_2.0.0     

loaded via a namespace (and not attached):
 [1] gtable_0.3.6       compiler_4.5.0     tidyselect_1.2.1   xml2_1.3.8        
 [5] textshaping_1.0.1  systemfonts_1.2.3  scales_1.4.0       fastmap_1.2.0     
 [9] R6_2.6.1           labeling_0.4.3     generics_0.1.4     pillar_1.10.2     
[13] RColorBrewer_1.1-3 tzdb_0.5.0         rlang_1.1.6        stringi_1.8.7     
[17] timechange_0.3.0   cli_3.6.5          withr_3.0.2        magrittr_2.0.3    
[21] digest_0.6.37      grid_4.5.0         hms_1.1.3          lifecycle_1.0.4   
[25] vctrs_0.6.5        glue_1.8.0         farver_2.1.2       ragg_1.4.0        
[29] gt_1.0.0           tools_4.5.0        pkgconfig_2.0.3    htmltools_0.5.8.1 

[olivroy]

Hi Mine! Thanks for the report. I can indeed reproduce. In #1935, there was a suggestion to update the default table placement to "t". Do you think a better option exists out there? I am not very good with LaTeX, but I remember that I used a lot "H!" as position to make sure the table didn't move too much.

I wonder what would the be best default

Maybe it would be better to avoid supplying a position by default? Would that be a good idea? @AaronGullickson

[AaronGullickson]

Yes, the document is technically rendering correctly, in the sense that gt tables rendered to pdf via quarto will float by default. The tables are floating, respectively, to the bottom and the top.

There are a two ways that users can change the default behavior. The first would be to use the chunk option tbl-pos to override the default float placement. I would recommend "h" here rather than "H" or "!H" as the latter two could create unexpected behavior (which was the source of the problem in #1935). The only catch to this approach is that it won't have any affect unless the user also uses a label that starts with a "tbl-" which might be a bit esoteric for some folks. Here is an example of that approach that will correct the problem:

---
title: "Title"
format: pdf
keep-tex: true
execute:
  echo: fenced
---

```{r}
library(knitr)
library(gt)
```

# Section 1

The `gt()` table is at the bottom of the page but it should be immediately below this text.

```{r}
#| label: tbl-test
#| tbl-cap: A table
#| tbl-pos: "h"
gt(mtcars[1:5,1:5])
```

This text should be below the table.

{{< pagebreak >}}

# Section 2

The `gt()` should be below this text, but it's showing up above it.

```{r}
#| label: tbl-test2
#| tbl-cap: Another table
#| tbl-pos: "h"
gt(mtcars[1:10,1:5])
```

{{< pagebreak >}}

# Section 3

The `kable()` table is correctly showing up below this text.

```{r}
kable(mtcars[10:20,1:5])
```

The tbl-cap is not necessary, but nice.

The second option is to set latex.use_longtable to TRUE in gt::tab_options. This is why the kable version works - kable uses a longtable rather than floating environment for latex tables. The longtable environment will just put a table in the text right where it goes. The downside is that this can (often) lead to tables being broken up across pages, which I think is enough of an impediment that I don't think it should be the default. Here is an example with that fix.

---
title: "Title"
format: pdf
keep-tex: true
execute:
  echo: fenced
---

```{r}
library(knitr)
library(gt)
```

# Section 1

The `gt()` table is at the bottom of the page but it should be immediately below this text.

```{r}
gt(mtcars[1:5,1:5]) |>
  tab_options(latex.use_longtable = TRUE)
```

This text should be below the table.

{{< pagebreak >}}

# Section 2

The `gt()` should be below this text, but it's showing up above it.

```{r}
#| label: tbl-test2
#| tbl-cap: Another table
#| tbl-pos: "h"
gt(mtcars[1:10,1:5]) |>
  tab_options(latex.use_longtable = TRUE)
```

{{< pagebreak >}}

# Section 3

The `kable()` table is correctly showing up below this text.

```{r}
kable(mtcars[10:20,1:5])
```

I expect that this may be an unfortunately somewhat routine complaint as some users do not like tables to float but rather want them to show up exactly where they are in the code. I think that logic makes sense for HTML documents, but not for paged documents like PDF documents, where this can cause tables to be split up across pages or can create ugly white space. Generally, the policy in professionally designed layout (e.g. academic journals) is to allow tables to float.

We could change the default format to something like "htb" so in simple documents like this you could still get the behavior the OP desires. However, in actual documents with more text, you are still likely to observe some floating behavior when a table cannot fit in the remaining page space, or would create empty white space below it because of lack of room for the next bit of content.

[olivroy]

thanks for your reply. I actually investigated more, and turns out removing \begin{table} and \end{table} from output does the trick and fixes the example here. as well as quarto-dev/quarto-cli#11653.

Edit: I don't know what to do at all

Another explanation of what should be done #2015 (review)

[AaronGullickson]

I am pretty sure that removing those will break floating tables altogether. The tabular environment within the table environment is not a floating environment.