---
title: "Getting Started with ggguides"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with ggguides}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6.5,
  fig.height = 4.5
)
library(ggguides)
library(ggplot2)

# Transparent backgrounds for pkgdown light/dark mode; base_size 17 keeps
# axis and legend text (0.8 x base_size) at 11 px or more on a phone
theme_set(
  theme_grey(base_size = 17) +
    theme(
      plot.background = element_rect(fill = "transparent", color = NA),
      panel.background = element_rect(fill = "transparent", color = NA),
      legend.background = element_rect(fill = "transparent", color = NA),
      legend.key = element_rect(fill = "transparent", color = NA),
      legend.box.background = element_rect(fill = "transparent", color = NA)
    )
)
```

## Installation

```{r eval=FALSE}
install.packages("ggguides")
```

Or the development version from GitHub:

```{r eval=FALSE}
# install.packages("pak")
pak::pak("gcol33/ggguides")
```

## Overview

**ggguides** simplifies common legend operations in ggplot2. Instead of memorizing
theme element names and their nested structure, you can use intuitive one-liner
functions to position, style, and manage legends.

**Key features:**

- Position legends with `legend_left()`, `legend_right()`, `legend_top()`, `legend_bottom()`, `legend_inside()`

- Style legends with `legend_style()` for fonts, backgrounds, and borders

- Wrap legend entries with `legend_wrap()` for multi-column layouts

- Collect legends from patchwork compositions with `collect_legends()`

## Basic Usage

Let's create a simple plot to demonstrate the legend helpers:
```{r base-plot, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the cylinders legend on the right."}
p <- ggplot(mtcars, aes(mpg, wt, color = factor(cyl))) +
  geom_point(size = 3) +
  labs(color = "Cylinders")

p
```

### Moving the Legend

Position the legend on any side with a single function call:

```{r position-left, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend on the left of the panel."}
p + legend_left()
```

```{r position-bottom, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend below the panel and its keys in a row."}
p + legend_bottom()
```

### Inside Positioning

Place the legend inside the plot area using coordinates or shortcuts:

```{r inside-topright, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend inside the panel in the top-right corner."}
p + legend_inside(position = "topright")
```

```{r inside-coords, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend inside the panel in the top-left corner."}
p + legend_inside(x = 0.02, y = 0.98, justification = c("left", "top"))
```

### Removing the Legend

```{r legend-none, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, without a legend."}
p + legend_none()
```

## Styling Legends

Use `legend_style()` to customize the legend appearance:

```{r style-size, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend title and labels drawn larger."}
p + legend_style(size = 18)
```

```{r style-full, fig.alt = "Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with a bold legend title and the legend on a cream box with an orange border."}
p + legend_style(
  size = 15,
  title_size = 20,
  title_face = "bold",
  background = "#FFF3E0",
  background_color = "#FF9800"
)
```

## Wrapping Legend Entries

For legends with many entries, use `legend_wrap()` to create multi-column layouts:

```{r wrap-example, fig.alt = "Scatter plot of highway mileage against engine displacement, points coloured by the seven car classes, with the legend keys in two columns on the right."}
ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(ncol = 2)
```

## Combining Functions

ggguides functions compose naturally with the `+` operator:

```{r combined, fig.alt = "Scatter plot of highway mileage against engine displacement, points coloured by the seven car classes, with the legend on the left on a cream box, its title in bold."}
ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_left() +
  legend_style(size = 15, title_face = "bold", background = "#FFF3E0")
```

```{r combined-wrap, fig.alt = "Scatter plot of highway mileage against engine displacement, points coloured by the seven car classes, with the legend below the panel and its keys in two columns."}
ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(ncol = 2) +
  legend_bottom()
```

## What's Next

- See the [Legend Positioning](positioning.html) article for detailed position control

- See the [Styling & Customization](styling.html) article for advanced styling options

- See the [Patchwork Integration](patchwork.html) article for multi-panel workflows