ggrepel

name: ggrepel description: R ggrepel package for non-overlapping text labels. Use for automatically positioning labels to avoid overlap in ggplot2.

Repel overlapping text labels in ggplot2.

Basic Usage

library(ggrepel)
library(ggplot2)

# Text labels that don't overlap
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(aes(label = name))

# Label boxes
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_label_repel(aes(label = name))

Selective Labeling

# Label only some points
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    data = subset(df, important == TRUE),
    aes(label = name)
  )

# Label top N
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    data = df %>% slice_max(value, n = 10),
    aes(label = name)
  )

Styling

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    aes(label = name),
    size = 3,
    color = "darkblue",
    fontface = "bold",
    family = "sans"
  )

# Label boxes with styling
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_label_repel(
    aes(label = name),
    fill = "white",
    color = "black",
    box.padding = 0.5,
    label.padding = 0.25,
    label.size = 0.25
  )

Segment Lines

# Customize connector lines
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    aes(label = name),
    segment.color = "grey50",
    segment.size = 0.5,
    segment.linetype = "dashed",
    segment.curvature = -0.1,
    segment.angle = 20
  )

# Arrow segments
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    aes(label = name),
    arrow = arrow(length = unit(0.02, "npc"))
  )

Repulsion Control

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    aes(label = name),
    force = 2,              # Repulsion force
    force_pull = 0.5,       # Pull toward data point
    max.overlaps = 20,      # Max overlaps before giving up
    max.iter = 10000,       # Max iterations
    max.time = 1            # Max seconds
  )

Direction Control

# Repel only horizontally
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(aes(label = name), direction = "x")

# Repel only vertically
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(aes(label = name), direction = "y")

# Both directions (default)
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(aes(label = name), direction = "both")

Nudging

# Nudge labels in a direction
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    aes(label = name),
    nudge_x = 0.5,
    nudge_y = 0.5
  )

Box Padding

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    aes(label = name),
    box.padding = 1,        # Padding around text
    point.padding = 0.5,    # Padding around points
    min.segment.length = 0  # Always show segments
  )

With Facets

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(aes(label = name)) +
  facet_wrap(~group)

Seed for Reproducibility

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(aes(label = name), seed = 42)

Handling Many Labels

# Limit overlaps
ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_repel(
    aes(label = name),
    max.overlaps = Inf,     # Show all labels
    verbose = TRUE          # Print progress
  )