Repository navigation
FAQ
Things that go wrong, and what they mean.
You opened it from file://. The site uses ES modules, and browsers refuse
module imports over the file:// protocol — so nothing loads and the page stays
empty. There is no build step, but there does have to be a server:
python -m http.server 8000
# then open http://localhost:8000/index.htmlAny static server works. This is the single most common way to see a blank page.
Hard-refresh. Modules cache aggressively — Ctrl+Shift+R (or Cmd+Shift+R).
A normal reload will happily serve you the old module.
The reader is deliberately strict, because it opens files people were sent by someone else. In order of how often it comes up:
-
It is really an old
.xls. That is a different format entirely — a compound binary document that can carry macros. Open it and save as.xlsxor.csv. -
The name disagrees with the bytes. A ZIP named
sales.csvis refused, and so is an.xlsxthat is really something else. The bytes decide, not the extension. - It is over 10MB. That is a hard ceiling. A chart that needs more than that wants a database, not a spreadsheet.
- The sheet is empty, or every row is blank.
Two things it will not do, by design: it never uploads your file anywhere, and
it never evaluates a formula. Only a cell's cached value is read, so
=WEBSERVICE(...) is inert.
The atlas spells some countries its own way. Natural Earth abbreviates to fit
labels on a map: Bosnia and Herz., Dem. Rep. Congo, Eq. Guinea. A
reasonable guess typed by hand matches nothing, and the map silently stays where
it was.
Use the country picker rather than typing — it is a searchable list of the 177
countries the atlas actually knows, so you cannot pick a name that does not
exist. Accents are folded and common aliases resolved (USA, Cote d'Ivoire
without its accents), but the picker removes the guesswork entirely.
If a country is grey on a choropleth, the name in your table did not match. Check it against the picker's spelling.
Header detection is a guess when the header row is numeric — label,2023,2024
over North,520,680 is genuinely undecidable by looking at it, because the
column names are numbers.
- In the data editor, headers are held separately from rows, so it never has to guess.
- In the gallery, there is a First row is a header tick box with the parsed column names shown beside it. If the guess was wrong, untick it and the names update.
Three do: the matrix, treemap and boxplot plugins come from unpkg, because they
are the only dependencies not vendored into lib/. Everything else — Chart.js,
D3, the sankey plugin — is served from the repo.
The studio's Sources panel lists every library a given chart uses, with its version and licence. That panel, the comment header on the JS tab, the script tags in the Standalone export and the gallery credits are all generated from one file, so they cannot drift apart.
Use the Standalone tab rather than assembling the HTML, CSS and JS tabs by hand. Standalone emits the script tags for the libraries that chart needs, in order, with the helper functions it depends on.
The individual tabs are the same code, but they assume you are supplying the
page and the <script> tags around them.
It will, and it says so first. The city list under a focused country ticks places onto the map one at a time; Add every city does the whole gazetteer for that country, and asks before it does when there are more than 400. The United States has 12,348. It will draw. You will not be able to read it.
A ticked city keeps whatever value it already had, and new ones arrive at 1 —
the same rule as everywhere else here: nothing invents a number on your behalf.
Yes — OpenCharts is MIT licensed, including the code you copy out of it.
The third-party libraries have their own licences, all permissive, listed in THIRD-PARTY-NOTICES.md. If you export a chart that uses Chart.js or D3, you are shipping those too.
Add &embed=1 to a studio URL and the page renders the chart alone — same page,
same renderer, studio hidden before first paint. Suitable for an <iframe>.
Or copy the Standalone export and host it yourself; it has no dependency on this site at all.
Open an issue. If it is a chart drawing incorrectly, the share link from the studio carries the whole spec in the URL — paste that and the exact state is reproducible.