Skip to contents

sdvplotR

sdvplotR plots sports team logos, wordmarks, player headshots and team colors across the 49 leagues of the SportsDataverse team index (sdv_leagues()) — NFL, NBA, WNBA, MLB, NHL, college football, men’s and women’s college basketball, soccer and more — in ggplot2 plots, gt tables and reactable tables, and in interactive plotly, ggiraph and leaflet charts and maps, with playing surfaces (59 of them: every court, field, rink and sheet, lacrosse, tennis, volleyball and curling included; the team leagues’ surfaces take a team’s colors) from sportyR. It is built on ggpath and unifies the approach established by nflplotR, cfbplotR, nbaplotR and mlbplotR behind one league argument.

Every NFL team's 2023 regular season drawn as its logo, placed by points scored and allowed per game.

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"))

Python

The same team colors, logos, wordmarks and headshots are on PyPI as sdvplot (Python 3.10+), with adapters for matplotlib and seaborn, plotnine, Plotly, Altair, Bokeh, HoloViews, great_tables and folium. sdvplot.great_tables ports this package’s table themes, cell styling, legends and image export. Docs: sdvplot.sportsdataverse.org. Source: sportsdataverse/sdvplot.

pip install sdvplot

JavaScript / TypeScript

They are also 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 team-aware function takes a league argument ("nfl", "nba", "wnba", "mlb", "nhl", "cfb", "mbb", "wbb", "soccer" and the rest of sdv_leagues()). Team identifiers are resolved automatically: full names, abbreviations from other data providers (ESPN, nflverse, MLB Stats, nba_api, NHL, CFBD, NCAA and more) and the codes of relocated franchises all resolve to the same team. sdv_resolve() shows the id a value resolves to, sdv_suggest() proposes candidates for a typo, and season selects the era for codes that were reused.

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 = sdv_teams("nfl")$abbr
)

ggplot(df, aes(x = a, y = b)) +
  geom_sdv_logos(aes(team = teams), league = "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(league = "nfl") +
  theme_minimal() +
  theme(axis.text.x = element_sdv_logo(league = "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", league = "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", league = "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(league = "nfl"), html = TRUE),
    wins = colDef(style = reactable_sdv_team_color_bar(df3, "team", league = "nfl"))
  )
)
# Interactive: the logo grid again, each logo with a tooltip (ggiraph) ...
p <- ggplot(df, aes(x = a, y = b)) +
  geom_sdv_logos_interactive(aes(team = teams, tooltip = teams, data_id = teams),
    league = "nfl", width = 0.075
  ) +
  theme_void()
ggiraph::girafe(ggobj = p)

# ... or logos on a native plotly chart (addSdvLogoMarkers() does maps)
plotly::plot_ly(df, x = ~a, y = ~b, type = "scatter", mode = "markers", text = ~teams) |>
  add_sdv_logos(df$a, df$b, df$teams, league = "nfl")

# A playing surface painted in a team's colors, ready for shot or play data
sdv_surface("nba", team = "BOS")
# ... or any of 59 surfaces, lacrosse to curling: see the Surfaces cookbook
sdv_surface("nll")

The Interactive Charts cookbook covers geom_sdv_logos_interactive() and its wordmark and headshot siblings, add_sdv_logos(), sdv_axis_logos() and sdv_colorway() for plotly, and addSdvLogoMarkers() for leaflet.

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 reactable helpers (reactable_sdv_logos(variant = "dark")) and sdv_logo_url(), and sdv_teams() exposes the full reference data (ESPN ids, colors, conference) for every team.

Documentation

The sdvplotR documentation website has the full function reference and every article; a selection:

🖼️ Browse the gallery: every article by its picture, each linking to the article that draws it.

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

Cookbooks: Getting Started · Social Posting · Leaderboard Dashboards · reactable Integration · Workflows · Logos in ggplot2 · Colors and Themes · Interactive: plotly, ggiraph, leaflet · Surfaces and Shot Charts

Interactive (ggiraph, plotly and leaflet; every per-sport and leaderboard article also ends with an interactive version): NFL EPA Scatter · NBA Net Rating · NHL Shot Map · MLB Run Differential · CFB Stadium Map · Team Maps with leaflet

Tables cookbook: SportsDataverse Table Themes · Table Theme Registry · Team Tables with the gt Toolkit · reactable and reactablefmtr · Saving and Posting Tables · Tier Lists and six more gtUtils recipes

Recipes: NFL EPA Scatter · Head-to-Head Card · Rank Bump Chart · Rolling Form and eleven more

Leaderboards: NFL · CFB · NBA · WNBA · MLB · NHL

Automation: Social Graphics, Automated

The articles index lists all of them.

See also the function reference and the NEWS.

Companion packages

  • sportyR draws the playing surfaces that sdvplotR paints in team colors.
  • ggpath is the image engine underneath the logo and headshot layers.
  • nflplotR and cfbplotR are the single-league packages whose conventions sdvplotR follows.
  • sdvplot (Python) and @sportsdataverse/sdvplot (JavaScript / TypeScript) are the twins in other languages.

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
sdvplot Python plots and tables
@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

X Follow

GitHub stars

Star history of sportsdataverse/sdvplotR

Our Authors

Cheat sheet

A printable four-page reference for sdvplotR: team logos, colors and scales in ggplot2, team identity, the plotly, ggiraph and leaflet integrations, surfaces, and the gt and reactable toolkits, in four color themes, light and dark.

📄 Download the sdvplotR cheat sheet (PDF)

Browse the other SportsDataverse cheat sheets at sportsdataverse.org/cheatsheets.

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}
}

License

sdvplotR is released under the MIT License; see LICENSE.md.