plotly.R: a generated README, an install command pointing elsewhere, and 25 demos

The README is generated, and the badge block is machine-managed

Before it says anything about the package, the file states where it came from: README.md is generated from README.Rmd, and edits belong in that other file. The consequence is visible in the raw text. Four badge links sit between explicit start and end HTML comments, and they resolve to the Actions status page, the CRAN package page for plotly, and two cranlogs badge URLs. Anything written between those markers is therefore replaced rather than appended to. A centered block right below the badges links to a project maintenance page on dash.plotly.com and carries no visible text of its own. The same kind of automation artifact sits in the repository root, where CLAUDE.md is filed next to plotly.Rproj, .Rbuildignore and .gitignore, none of which the README mentions. Editing this file by hand is the one thing that header tells you not to do.

The development install command names plotly/plotly, not this repository

Two install routes are given, and only the first one matches the repository it lives in. The CRAN route installs the published package by name. The second route is described as the latest development version on GitHub, and the command it hands you points at plotly/plotly rather than at the path this project occupies. Both of the file's own repository links disagree with that string: the badges target the Actions workflow under plotly/plotly.R, and the contributing link resolves into plotly/plotly.R/blob/master/CONTRIBUTING.md. So the development command either resolves to a different repository that publishes a package of the same name, or it is a leftover string from an earlier rename, and nothing in the text settles which.

install.packages("plotly")

remotes::install_github("plotly/plotly")

ggplotly() replicates the static plot first, and style() comes after

The default behaviour of `ggplotly()` is to reproduce the static ggplot2 version exactly, and the text is explicit that this exactness applies before any interaction occurs. Greater control over interactive behaviour is therefore opt-in rather than automatic. Two hooks are offered for it. `dynamicTicks` is described as one of the convenient high-level arguments on the function itself, and it tells plotly.js to recompute axes dynamically when appropriate. `style()` then modifies the underlying trace attributes that produce the plot, with hoveron given as the example, and the sample call sets three of them at once: which points trigger the hover, what the hover text contains, and the background colour of the hover label.

library(plotly)
g <- ggplot(faithful, aes(x = eruptions, y = waiting)) +
  stat_density_2d(aes(fill = ..level..), geom = "polygon") +
  xlim(1, 6) + ylim(40, 100)
ggplotly(g)

gg <- ggplotly(g, dynamicTicks = "y")
style(gg, hoveron = "points", hoverinfo = "x+y+text", hoverlabel = list(bgcolor = "white"))

The conversion returns a plain plotly object, and plotly_json() shows its JSON

Because the conversion hands back a plotly object rather than a special wrapper, essentially any function in the package can be applied to it afterwards. Four are named, and each is a different kind of edit. `layout()` customizes the layout. `add_traces()` appends traces or data, and it has higher level `add_*()` siblings such as `add_polygons()` for the same job. `subplot()` combines several plotly objects into one view. `plotly_json()` inspects the underlying JSON sent to plotly.js. That last one is the useful escape hatch, since it is the only documented route to what the ggplot2 pipeline actually produced rather than what you assumed it produced. The same permissiveness applies on the way in: `ggplotly()` respects three unofficial ggplot2 aesthetics that carry no ggplot2 meaning of their own. One is `text`, which customizes the tooltip, one is `frame`, which creates animations, and one is `ids`, which exists to make transitions between views come out sensible. Passing any of them through a ggplot2 layer that knows nothing about interactivity is the whole trick, and it is why the wrapper is thin rather than a parallel drawing system.

plot_ly() exists because the ggplot2 API will never carry surface or mesh

The second entry point is justified by what ggplot2 cannot express. `plot_ly()` talks to plotly.js more directly, which the text says lets you reach more specialized chart types, naming parallel coordinates and maps, and some visualization that the ggplot2 API will never support, naming surface, mesh and trisurf. The shortest example in the whole file uses a dataset that ships with R and nothing else, with a single type argument switching on a surface plot. So the argument for keeping a second entry point is not stylistic. The rendering surface belongs to plotly.js and ggplot2 has no layer for it, and a user who wants a mesh should not have to force one through a statistical grammar. Everything downstream of that call is the same object model described in the previous section, which is why `layout()`, `subplot()` and `add_traces()` are not introduced separately for this path.

plot_ly(z = ~volcano, type = "surface")

Two conduct files, one pointer, and a documentation split drawn twice

The contributing paragraph sends everything to a single file, CONTRIBUTING.md, and says that file covers opening issues, asking questions, contributing changes, and the code of conduct. The repository root disagrees about where the code of conduct lives: both CONDUCT.md and CODE_OF_CONDUCT.md sit at the top level, so there are two candidates and only one pointer. The learn-more paragraph draws a sharper line between two documentation sites than it does between versions of anything: the pages under plotly.com/r are called essentially a language agnostic how to guide for learning plotly.js, while plotly-r.com is presented as the more complete tutorial written by and for the R user. That R-specific site is where the feature list lives, and the list is short: client-side linking, shiny integration, editing and generating static images, and custom events in JavaScript. The examples the package carries are listed by command rather than by file, with `demo(package = "plotly")` for the shipped demos and `plotly_example("shiny")` or `plotly_example("rmd")` for the application examples. Third-party material is pointed at as well, with slide decks of examples and concepts kept by Carson at talks.cpsievert.me.

demo(package = "plotly")

Thirteen crosstalk demos, seven sf demos, and no mention of either

The demo filenames carry most of what the prose leaves out. Of the twenty five entries listed, thirteen are crosstalk files, split between filtering on a dynamic axis, filtering lines, highlighting across three binned target variants, and separate introductory, pipeline, subplot, ggpairs, ggplotly, leaflet and epl examples. Seven more are sf files, three of them aimed at Mapbox data, layout and style, plus one 3D globe example. Two are animation tours, over USArrests and a basic case. Two are standalone, custom-javascript.R and rotate.R. The index file is demo/00Index, with no extension. None of the three packages this folder leans on is named anywhere in the README, including crosstalk, which is the mechanism behind the client side linking the file advertises, and sf. The install section meanwhile states no system requirements at all, so a reader working down the demo list finds out what is needed only by running the examples.

The license field records no determination next to two license files

The repository's license metadata reads NOASSERTION, which is an absent determination rather than a statement about terms. The tree carries both a LICENSE file and a LICENSE.md at the root, and the README links neither. Two files with adjacent names may also be two different licenses covering different content, so the text does not settle which one governs the sources under R/ as against anything under inst/. The check worth making is direct rather than inferential: read both files, confirm which covers the package code, and treat the empty metadata field as a reason to do that before redistributing anything. The rest of the root has the ordinary shape of an R package, with DESCRIPTION, NAMESPACE, man/, tests/, data/, data-raw/, inst/, tools/ and NEWS.md carrying the change log. The recorded release trail is v4.11.0 on 2025-06-19, v4.12.0 on 2026-01-24, and v4.12.1 on 2026-07-25.

Editorial conclusion

plotly.R is worth installing for anyone who wants plotly.js output from R without writing the JavaScript, and the CRAN route is the one to start on, because the development route points at a different repository path than this one. Before building anything on top of it, read the two license files yourself: the metadata field records no determination and the README links neither. Expect to leave the README behind quickly, since the crosstalk, sf and Mapbox demos dominate the demo folder and none of those three names appears anywhere in the prose.

Frequently asked questions

Official sources

1. Issues
2. plotly/plotly.R on GitHub
3. Project website
4. README
5. Releases