---
title: "legend_block"
---

[< Back to Reference](../reference.qmd) | [View source](https://codeberg.org/usrbinr/stwd/src/branch/main/R/blocks.R#L354)

# `legend_block()`

Create a Legend Block Plot

## Usage

```r
legend_block(
  colors,
  halign = "right",
  valign = "center",
  orientation = "horizontal",
  sep = " | ",
  size = 10,
  bold = TRUE,
  uppercase = FALSE,
  lineheight = 1.6,
  width = 0.95,
  wrap_width = NULL,
  margin_top = 0,
  margin_bottom = 5,
  margin_left = 5,
  margin_right = 5,
  ...
)
```

## Arguments

| Argument | Description |
|----------|-------------|
| `colors` | Named vector where names are category labels and values are colors (hex codes or R color names). |
| `halign` | Horizontal alignment: "left", "center", or "right". Default: "right". |
| `valign` | Vertical alignment (for vertical orientation): "top", "center", or "bottom". Default: "center". |
| `orientation` | Either "horizontal" (labels side by side) or "vertical" (labels stacked). Default: "horizontal". |
| `sep` | Separator between category labels (horizontal only). Default: " \| ". |
| `size` | Text size in pts. Default: 10. |
| `bold` | Logical; make labels bold? Default: TRUE. |
| `uppercase` | Logical; convert labels to uppercase? Default: FALSE. |
| `lineheight` | Line height multiplier for vertical legends. Default: 1.6. |
| `width` | Text width for wrapping (0-1). Default: 0.95. |
| `wrap_width` | Character width to wrap labels at. Useful for long labels in vertical legends. Default: NULL (no wrapping). |
| `margin_top` | Top margin in pts. Default: 0. |
| `margin_bottom` | Bottom margin in pts. Default: 5. |
| `margin_left` | Left margin in pts. Default: 5. |
| `margin_right` | Right margin in pts. Default: 5. |
| `...` | Additional arguments passed to `marquee::geom_marquee()`. |

## Value

A ggplot object that can be combined with other plots via patchwork.

## Description

Creates a standalone inline legend as a ggplot, showing colored category
labels separated by a delimiter. Use above/below charts or beside them
in patchwork compositions to replace traditional legends with clean text.

## Details

Legend blocks follow SWD principles by embedding color meaning directly
in text rather than requiring readers to cross-reference a separate legend.
The colored labels can be positioned horizontally (as a row of labels
with separators) or vertically (stacked labels). Combine with other
block functions via patchwork to build complete story layouts.

The function uses marquee syntax internally to render colored text.
Each category label is wrapped in its assigned color, with optional
bold formatting and case transformation.

## Examples

```r
## Not run: 
library(patchwork)

legend_colors <- c("ACCURATE" = "#808080", "NULL" = "#B0B0B0", "ERROR" = "#E69F00")

# Horizontal above chart
legend_plot <- legend_block(legend_colors, halign = "right")

# Vertical beside chart
legend_vert <- legend_block(legend_colors, orientation = "vertical", valign = "top")

title_block("My Title") / legend_plot / my_chart +
    plot_layout(heights = c(0.08, 0.04, 0.88))

## End(Not run)
```

