sdvplotR

sdvplotR plots sports team logos, wordmarks, player headshots and team colors across nine leagues — NFL, NBA, WNBA, MLB, NHL, college football, men’s and women’s college basketball, and soccer — in ggplot2 plots, gt tables and reactable tables. It is built on ggpath and unifies the approach established by nflplotR, cfbplotR, nbaplotR and mlbplotR behind one sport argument.

Part of the SportsDataverse family of R packages for sports analytics.

Data freshness and pipeline status for every SportsDataverse dataset: sportsdataverse.org/status.

Installation

Once on CRAN, install the released version with:

install.packages("sdvplotR")

Install the development version of sdvplotR from GitHub with:

# using the pak package (recommended):
if (!requireNamespace("pak", quietly = TRUE)) {
  install.packages("pak")
}
pak::pak("sportsdataverse/sdvplotR")

# or from R-universe (binary builds):
install.packages("sdvplotR", repos = c("https://sportsdataverse.r-universe.dev", "https://cloud.r-project.org"))

JavaScript / TypeScript

The same team colors, logos, wordmarks and headshots are on npm as @sportsdataverse/sdvplot, with Observable Plot, D3, React and chart-library integrations plus shot charts. @sportsdataverse/sdvtables is the counterpart to the gt table helpers. Docs: plot.sportsdataverse.org. Source: sportsdataverse/sdvplot-js.

npm install @sportsdataverse/sdvplot @sportsdataverse/sdvtables @sportsdataverse/sporty

Usage

Every function takes a sport argument ("nfl", "nba", "wnba", "mlb", "nhl", "cfb", "mbb", "wbb", "soccer"). Team keys are cleaned automatically: full names, alternate abbreviations used by other data providers and historical abbreviations of relocated franchises ("OAK" → "LV", "SEA" → "OKC") all resolve to the same team.

library(sdvplotR)
library(ggplot2)

# NFL team logos in a grid
df <- data.frame(
  a     = rep(1:8, 4),
  b     = sort(rep(1:4, 8), decreasing = TRUE),
  teams = valid_team_names("nfl")
)

ggplot(df, aes(x = a, y = b)) +
  geom_sdv_logos(aes(team = teams), sport = "nfl", width = 0.075) +
  theme_void()

# Logos as axis labels + team colours as fill
df2 <- data.frame(
  team  = c("KC", "BUF", "SF", "DAL"),
  score = c(42, 38, 35, 30)
)

ggplot(df2, aes(x = team, y = score)) +
  geom_col(aes(fill = team), show.legend = FALSE) +
  scale_fill_sdv(sport = "nfl") +
  theme_minimal() +
  theme(axis.text.x = element_sdv_logo(sport = "nfl", size = 1))

library(gt)

# Logos inside a gt table, in the SportsDataverse table theme
data.frame(team = c("KC", "BUF", "SF"), wins = c(13, 12, 11)) |>
  gt() |>
  gt_sdv_logos(columns = "team", sport = "nfl") |>
  gt_theme_sdv()

# ...or dressed in one team's colors
data.frame(player = c("Patrick Mahomes", "Travis Kelce"), yards = c(4183, 984)) |>
  gt() |>
  gt_theme_sdv_team(team = "KC", sport = "nfl")

library(reactable)

# Logos inside a reactable table with team-coloured bars
df3 <- data.frame(team = c("KC", "BUF", "SF"), wins = c(13, 12, 11))

reactable(
  df3,
  columns = list(
    team = colDef(cell = reactable_sdv_logos(sport = "nfl"), html = TRUE),
    wins = colDef(style = reactable_sdv_team_color_bar(df3, "team", sport = "nfl"))
  )
)

gt_theme_sdv() (light or style = "dark") and gt_theme_sdv_team() are the SportsDataverse table themes. The gt side also carries the gtUtils toolkit by Andrew Weatherman: 18 table themes (gt_theme_kenpom(), gt_theme_savant(), gt_theme_athletic(), …), color legends, cut lines, significance notation, outlier flags, faceted grids and gt_save_crop() / gt_social_crop() for publishing.

Dark-mode logo variants are available through variant = "dark" in the table helpers, and team_reference() exposes the full reference data (ESPN ids, colors, conference / division) for every team.

Documentation

The sdvplotR documentation website has the full function reference and these articles:

Per-sport (each with companion SportsDataverse package examples): NFL · CFB · NBA · WNBA · MLB · NHL · MBB · WBB

Cookbooks: Getting Started · Social Posting · Leaderboard Dashboards · reactable Integration · Workflows

A printable sdvplotR cheat sheet will join the set covering every SportsDataverse package.

The SportsDataverse

sdvplotR draws the pictures; the companion packages fetch the data.

Package	Sport / Scope
cfbfastR	College football
hoopR	Men’s basketball (NBA and NCAA)
wehoop	Women’s basketball (WNBA and NCAA)
fastRhockey	Hockey (NHL and PWHL)
baseballr	Baseball (MLB, MiLB, NCAA)
nflfastR · nflreadr	NFL play-by-play and data loaders
oddsapiR	Sports betting odds
cfbseedR	CFB seeding and playoff simulation
sportyR	Playing-surface plots
sportsdataverse-R	Umbrella R metapackage
@sportsdataverse/sdvplot · @sportsdataverse/sdvtables	JavaScript / TypeScript plots and tables
sportsdataverse-py · sportsdataverse.js	Python and Node.js

See the full ecosystem at sportsdataverse.org.

Follow the SportsDataverse on X and star this repo

Our Authors

• Saiem Gilani
  

• Sebastian Carl
  

• Jared Lee
  

• Camden Kay
  

• Andrew Weatherman (gtUtils)
  

Code of Conduct

Please note that the sdvplotR project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Citations

To cite the sdvplotR R package in publications, use:

BibTeX Citation

@misc{gilani_carl_lee_kay_weatherman_sdvplotR,
  author = {Gilani, Saiem and Carl, Sebastian and Lee, Jared and Kay, Camden and Weatherman, Andrew},
  title = {sdvplotR: The SportsDataverse's R Package for Multi-League Sports Plotting.},
  url = {https://sdvplotR.sportsdataverse.org},
  year = {2026}
}