gt_split.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{gt_split}
\alias{gt_split}
\title{Split a table into a group of tables (a \code{gt_group})}
\usage{
gt_split(data, row_every_n = NULL, row_slice_i = NULL, col_slice_at = NULL)
}
\arguments{
\item{data}{\emph{The gt table data object}

\verb{obj:<gt_tbl>} // \strong{required}

This is the \strong{gt} table object that is commonly created through use of the
\code{\link[gt:gt]{gt::gt()}} function.}

\item{row_every_n}{\emph{Split at every n rows}

\verb{scalar<numeric|integer>} // \emph{default:} \code{NULL} (\code{optional})

A directive to split at every \emph{n} number of rows. This argument expects a
single numerical value.}

\item{row_slice_i}{\emph{Row-slicing indices}

\verb{vector<numeric|integer>} // \emph{default:} \code{NULL} (\code{optional})

An argument for splitting at specific row indices. Here, we expect either a
vector of index values or a function that evaluates to a numeric vector.}

\item{col_slice_at}{\emph{Column-slicing locations}

\verb{<column-targeting expression>} // \emph{default:} \code{NULL} (\code{optional})

Any columns where vertical splitting across should occur. The splits occur
to the right of the resolved column names. Can either be a series of column
names provided in \code{c()}, a vector of column indices, or a select helper
function (e.g. \link[gt]{starts_with}, \link[gt]{ends_with}, \link[gt]{contains}, \link[gt]{matches},
\link[gt]{num_range}, and \link[gt]{everything}).}
}
\value{
An object of class \code{gt_group}.
}
\description{
With a \strong{gt} table, you can split it into multiple tables and get that
collection in a \code{gt_group} object. This function is useful for those cases
where you want to section up a table in a specific way and print those
smaller tables across multiple pages (in RTF and Word outputs, primarily via
\link[gt]{gtsave}, or, with breaks between them when the output context is HTML.
}
\note{
This function is a temporary export of asar, but all development and rights
belong to \code{rstudio/gt}. This function provides a fix to the function
introduced by a bug in gt v1.3.0. Until this is corrected in the package, we
are using the function here. Once this bug is patched, we will deprecate
and remove this function from asar and direct users to use the gt package
version of this function.rom
}
\section{Examples}{


Use a subset of the \code{\link[gt:gtcars]{gt::gtcars}} dataset to create a \strong{gt} table. Format the
\code{msrp} column to display numbers as currency values, set column widths with
\link[gt]{cols_width}, and split the table at every five rows with \code{gt_split()}.
This creates a \code{gt_group} object containing two tables. Printing this object
yields two tables separated by a line break.

\if{html}{\out{<div class="sourceCode r">}}\preformatted{gtcars |>
  dplyr::slice_head(n = 10) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt() |>
  fmt_currency(columns = msrp) |>
  cols_width(
    year ~ px(80),
    everything() ~ px(150)
  ) |>
  gt_split(row_every_n = 5)
}\if{html}{\out{</div>}}

Use a smaller subset of the \code{\link[gt:gtcars]{gt::gtcars}} dataset to create a \strong{gt} table.
Format the \code{msrp} column to display numbers as currency values, set the table
width with \code{\link[gt:tab_options]{gt::tab_options()}} and split the table at the \code{model} column This
creates a \code{gt_group} object again containing two tables but this time we get
a vertical split. Printing this object yields two tables of the same width.

\if{html}{\out{<div class="sourceCode r">}}\preformatted{gtcars |>
  dplyr::slice_head(n = 5) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt() |>
  fmt_currency(columns = msrp) |>
  tab_options(table.width = px(400)) |>
  gt_split(col_slice_at = "model")
}\if{html}{\out{</div>}}
}

\section{Function ID}{

14-2
}

\section{Function Introduced}{

\code{v0.9.0} (Mar 31, 2023)
}

\concept{table group functions}