% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/guide-legend-group.R
\name{guide_legend_group}
\alias{guide_legend_group}
\title{Grouped legend}
\usage{
guide_legend_group(
  key = "group_split",
  title = waiver(),
  override.aes = list(),
  nrow = NULL,
  ncol = NULL,
  theme = NULL,
  position = NULL,
  direction = NULL,
  order = 0L
)
}
\arguments{
\item{key}{A \link[=key_group]{group key} specification. Defaults to
\code{key_group_split()} to split labels to find groups.}

\item{title}{One of the following to indicate the title of the guide:
\itemize{
\item A \verb{<character[1]>} or \verb{<expression[1]>} to set a custom title.
\item \code{NULL} to not display any title.
\item \code{\link[ggplot2:waiver]{waiver()}} (default) to take the name of the scale
object or the name specified in \code{\link[ggplot2:labs]{labs()}} as the title.
}}

\item{override.aes}{A named \verb{<list>} specifying aesthetic parameters of the
key glyphs. See details and examples in
\code{\link[ggplot2:guide_legend]{guide_legend()}}.}

\item{nrow, ncol}{A positive \verb{<integer[1]>} setting the desired dimensions of
the legend layout. Either \code{nrow} or \code{ncol} can be set, but not both,}

\item{theme}{A \code{\link[ggplot2:theme]{<theme>}} object to style the guide individually or
differently from the plot's theme settings. The \code{theme} argument in the
guide overrides and is combined with the plot's theme.}

\item{position}{A \verb{<character[1]>} giving the location of the guide. Can be one of \code{"top"},
\code{"bottom"}, \code{"left"} or \code{"right"}.}

\item{direction}{A \verb{<character[1]>} indicating the direction of the guide. Can be on of
\code{"horizontal"} or \code{"vertical"}.}

\item{order}{A positive \verb{<integer[1]>} that specifies the order of this guide among
multiple guides. This controls in which order guides are merged if there
are multiple guides for the same position. If \code{0} (default), the order is
determined by a hashing indicative settings of a guide.}
}
\value{
A \verb{<GuideLegend>} object.
}
\description{
This legend resembles \code{ggplot2::guide_legend()}, but has the ability to
keep groups in blocks with their own titles.
}
\details{
\subsection{Styling options}{

Below are the \link[ggplot2:theme]{theme} options that determine the styling of
this guide.\tabular{lll}{
   \strong{Theme setting} \tab \strong{Type} \tab \strong{Description} \cr
   \code{legendry.legend.subtitle} \tab \code{\link[ggplot2:element_text]{element_text()}} \tab Title of groups in the legend. \cr
   \code{legendry.legend.subtitle.position} \tab \verb{<character[1]>} \tab One of \code{"top"}, \code{"right"}, \code{"bottom"} or \code{"left"}. \cr
   \code{legendry.group.spacing} \tab \code{\link[=unit]{unit()}} \tab Spacing in between groups of keys. \cr
   \code{legend.background} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Background of the legend. \cr
   \code{legend.margin} \tab \code{\link[ggplot2:margin]{margin()}} \tab Padding around the legend. \cr
   \code{legend.text} \tab \code{\link[ggplot2:element_text]{element_text()}} \tab Labels displayed next to keys. \cr
   \code{legend.text.position} \tab \verb{<character[1]>} \tab One of \code{"top"}, \code{"right"}, \code{"bottom"} or \code{"left"}. \cr
   \code{legend.title} \tab \code{\link[ggplot2:element_text]{element_text()}} \tab Title of the legend. \cr
   \code{legend.title.position} \tab \verb{<character[1]>} \tab One of \code{"top"}, \code{"right"}, \code{"bottom"} or \code{"left"}. \cr
   \code{legend.key} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Background of the key areas. \cr
   \code{legend.key.height} \tab \code{\link[=unit]{unit()}} \tab Height of keys. \cr
   \code{legend.key.width} \tab \code{\link[=unit]{unit()}} \tab Width of keys. \cr
   \code{legend.key.justification} \tab \verb{<numeric[2]>} \tab Justification for placing legend keys in excess space. \cr
   \code{legend.key.spacing.x} \tab \code{\link[=unit]{unit()}} \tab Horizontal spacing between keys. \cr
   \code{legend.key.spacing.y} \tab \code{\link[=unit]{unit()}} \tab Vertical spacing between keys. Taken literally. \cr
   \code{legend.byrow} \tab \verb{<logical[1]>} \tab Row-order key filling (\code{TRUE}) or column-order (\code{FALSE}) \cr
}


The context-agnostic alternative to using \code{theme()} is to use
\code{\link[=theme_guide]{theme_guide()}}:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{guide_legend_group(theme = theme_guide(
  subtitle = element_text(),
  subtitle.position = "top",
  group.spacing = unit(5, "mm"),
  text = element_text(),
  text.position = "right",
  title = element_text(),
  title.position = "top",
  key = element_rect(),
  key.height = unit(5, "mm"),
  key.width = unit(5, "mm"),
  key.justification = c(0.5, 0.5),
  key.spacing.x = unit(5, "mm"),
  key.spacing.y = unit(5, "mm"),
  byrow = TRUE,
  margin = margin(5),
  background = element_rect(),
))
}\if{html}{\out{</div>}}
}
}
\examples{
# Standard plot for selection of `msleep`
df <- msleep[c(9, 28, 11, 5, 34, 54, 64, 24, 53), ]

p <- ggplot(df) +
  aes(bodywt, awake, colour = paste(order, name)) +
  geom_point()

# By default, groups are inferred from the name
p + guides(colour = "legend_group")

# You can also use a look-up table for groups
# The lookup table can be more expansive than just the data:
# We're using the full 'msleep' data here instead of the subset
lut <- key_group_lut(msleep$name, msleep$order)

p + aes(colour = name) +
  guides(colour = guide_legend_group(key = lut))

# `nrow` and `ncol` apply within groups
p + guides(colour = guide_legend_group(nrow = 1))

# Groups are arranged according to `direction`
p + guides(colour = guide_legend_group(ncol = 1, direction = "horizontal")) +
  theme(legend.title.position = "top")

# Customising the group titles
p + guides(colour = "legend_group") +
  theme(
    legendry.legend.subtitle.position = "left",
    legendry.legend.subtitle = element_text(
      hjust = 1, vjust = 1, size = rel(0.9),
      margin = margin(t = 5.5, r = 5.5)
    )
  )

# Changing the spacing between groups
p + guides(colour = "legend_group") +
  theme(legendry.group.spacing = unit(0, "cm"))
}
\seealso{
Other standalone guides:
\code{\link[=guide_axis_annotation]{guide_axis_annotation()}},
\code{\link[=guide_axis_base]{guide_axis_base()}},
\code{\link[=guide_axis_dendro]{guide_axis_dendro()}},
\code{\link[=guide_axis_nested]{guide_axis_nested()}},
\code{\link[=guide_axis_plot]{guide_axis_plot()}},
\code{\link[=guide_axis_symbols]{guide_axis_symbols()}},
\code{\link[=guide_circles]{guide_circles()}},
\code{\link[=guide_colbar]{guide_colbar()}},
\code{\link[=guide_colring]{guide_colring()}},
\code{\link[=guide_colsteps]{guide_colsteps()}},
\code{\link[=guide_legend_base]{guide_legend_base()}},
\code{\link[=guide_legend_cross]{guide_legend_cross()}},
\code{\link[=guide_legend_manual]{guide_legend_manual()}}

Other legend guides:
\code{\link[=guide_legend_base]{guide_legend_base()}},
\code{\link[=guide_legend_cross]{guide_legend_cross()}},
\code{\link[=guide_legend_manual]{guide_legend_manual()}}
}
\concept{legend guides}
\concept{standalone guides}
