 | Support level: Pending The support level for this extension is currently under review. TheReader Growth Team is the maintainer of last resort for the time being. |
 Release status: stable | |
|---|---|
 | |
| Implementation | Tag |
| Description | Renders charts |
| Author(s) | Brooke Vibber, Katie Filbert, Roan Kattouw |
| Compatibility policy | Master maintains backward compatibility. |
| MediaWiki | >= 1.45 |
| Database changes | No |
| License | GNU General Public License 3.0 or later |
| Download | README |
| |
| Translate the Chart extension if it is available at translatewiki.net | |
| Issues | Open tasks ·Report a bug |
TheChart extension provides basic interactivedata visualization capabilities designed to replace some but not all aspects of theGraph extension.This extension is currently in development for Wikimedia wikis.SeeExtension:Chart/Project for more details on the development process.
This extension supports the following chart types:
The Chart extension requires having theJsonConfig extension installed, as well as downloading theChart Renderer JavaScript (actually TypeScript) library.
See theREADME.md file in the repository for the full setup instructions.
For Wikimedia production usage, seewikitech:Kubernetes/Deployments for general instructions on service deployments.
To render a chart, you must define a chart definition to associate with thetabular data source you want to render.A chart definition is structured as a relatively simple JSON file; seeExtension:Chart/Specification for the syntax details.
All the charts in this example can be rendered from the same data source:Data:Chart Example Data.tab, a fictional dataset.Sample contents for these pages can be found in thesample directory.
{"license":"CC0-1.0","version":1,"source":"Chart Example Data.tab","type":"line","title":{"en":"Example Chart Title"},"subtitle":{"en":"Example Subtitle"},"xAxis":{"title":{"en":"Example X Axis Title"},"format":"none"},"yAxis":{"title":{"en":"Example Y Axis Title"},"format":"none"},"mediawikiCategories":[{"name":"Example category","sort":"Its sortkey"}],"transform":{"module":"Optional lua module for data transforms","function":"transform_func","args":{"arg_name":"arg_value"}}}
Once a chart is defined, you can render it easily using the #chart parser function.In this case, the chart data is defined inData:Chart Example Data.tab, and the chart itself is defined inData:Example.Line.chart:
{{#chart:Example.Line.chart}}
Note that a chart can be generic and reused with different data sources, like so:
{{#chart:Population through years.chart|data=Population of USA.tab}}
{{#chart:Population through years.chart|data=Population of UK.tab}}
{{#chart:Population through years.chart|data=Population of Poland.tab}}
When creating charts with dates on the x-axis, dates in tabular data should be formatted as strings that are exactly 10 characters long in the format:
YYYY-MM-DD, e.g.,2025-10-20Other 10 character strings that are parseable by JavaScript'sDate.parse() function may also work, though not officially supported.
When dates are detected in the first column of the tabular data, they will be automatically localized based on the wiki's content language.
{"license":"CC0-1.0","description":{"en":"1993 Canadian federal election"},"mediawikiCategories":[{"name":"Data:.tab","sort":""},{"name":"Data:Examples.tab","sort":""}],"schema":{"fields":[{"name":"date","type":"string","title":{"en":"Date","fr":"Date"}},{"name":"pc","type":"number","title":{"en":"PC","fr":"PC"}},{"name":"liberal","type":"number","title":{"en":"Liberal","fr":"Libéral"}},{"name":"ndp","type":"number","title":{"en":"NDP","fr":"NPD"}},{"name":"bq","type":"number","title":{"en":"BQ","fr":"BQ"}},{"name":"reform","type":"number","title":{"en":"Reform","fr":"Réform"}}]},"data":[["1993-09-09",35,37,8,8,10],["1993-09-14",36,33,8,10,11],["1993-09-20",35,35,6,11,11]]}
See examples on Commons:
For years, the dates should be numbers:
{"license":"CC0-1.0","description":{"en":"New Zealand annual wine production, in millions of litres"},"sources":"Statistics from New Zealand Winegrowers 1998–2024 annual reports","schema":{"fields":[{"name":"year","type":"number","title":{"en":"Year"}},{"name":"production","type":"number","title":{"en":"Wine produced (million litres)"}}]},"data":[[1990,54.4],[1991,49.9],[1992,41.6],[1993,32.5],[1994,41.1],[1995,56.4]]}
Example of charts and tabular data with years on the x axis:
SeeSupport for dates ADR in gerrit for more details on date support.
Customization of charts is currently limited.The hope is that, after testing, discussion and evaluation, solutions for customization can be found that do not compromise accessibility, device-specific rendering, or security.
Currently, charts occupy the entire container width where you place them.
The eventual goal is to ensure that charts can be rendered legibly no matter what device they are read on; seeT376845 for more details.
Currently, charts are restricted to a single default color palette.This palette has been carefully designed with accessibility in mind.The thinking behind these color choices can be explored inT369863.
Some charts do require specific color themes, for example, to represent data relating to political parties.It remains an open question of how best to support this type of customization without compromising the ability of readers with accessibility needs (e.g., color blindness) to use them.
Note, while chart's currently render SVG output which can be styled viaTemplateStyles, please note that styling associated SVG elements shouldnot be consideredstable as it may change at any time.Please do not rely on CSS to alter chart appearance as this may result in non-functional charts in future or may interfere with accessibility features that change font size and features such asdark mode.
Charts can only be embedded in the wiki's content language; so, for example, the "uselang" query string (e.g.?uselang=es) will not impact the chart.
The chart format supports defining text like title and labels in different languages, so that the same chart can be used in wikis of different languages.Seethis example of a chart with support for multiple languages being displayed in a Spanish-language wiki.
Seethis filtered view of the Charts Phabricator board.
For all charts, data is expected to be arranged in columns, with the first column representing thex-axis and the following columns representing series or curves on they-axis.
In the following example, the{{#chart:}} is wrapped in an {{Image frame}} container to set the chart’s width and include a caption.A link is also provided to the raw tabular data, where information on data sources may be found:
{{image frame|content={{#chart:Example.Line.chart}}[[commons:Data:Chart Example Data.tab|'''Raw data''']]|width= 340|caption= This is an example of a line chart.}}
See the result in this section.
Here the chart spans the full width of the page content area:
{{#chart:Example.Bar.chart}}<divalign="center">[[commons:Data:Chart Example Data.tab|'''Raw data''']]</div>
This results in:
Pie charts are a special chart type, and data sources may require modification to be rendered appropriately.
When reading data, any non-number columns (e.g., the x-axis) will be discarded, and the sum of all rows will be represented on the chart.
For example, where multiple rows depict values for A, B, and C on numerous dates, e.g., January 1st and January 2nd, the pie chart segment for A will represent the sum of all A's row values across those dates.
Charts that can be used in articles live on Wikimedia Commons and can be tracked using MediaWiki categories.
This query can be used as a proxy to find charts that others have made and contribute translations, andthis to find tab pages that may be used to produce charts.
The set of wiki pages that use charts on any particular wiki can be found in the category whose name is defined atMediaWiki:chart-render-category andMediaWiki:Chart-error-category (Category:Pages using the Chart extension andCategory:Pages using the Chart extension with rendering errors on this wiki).Please make sure to connect your wiki categories tod:Q131382738 andd:Q131406605 to make the interwiki search easier.
Please see the categoryWikipedia pages with disabled graphs in various languages for old graphs that need to be migrated to the Charts extension.Some have however already been deleted without replacing them with new charts.The list can be compared with anarchived list of the first 200 out of 23,811 English Wikipedia pages with disabled graphs from 2023, soon after the templates were added to that category, and corresponding in other languages.
Given the problems withExtension:Graph, all the decisions regarding the new extension have been carefully considered, with the hope of building trust and confidence in its replacement.
So far, the technical decisions are documented in the code repository in the/doc/adr folder.
Failing .chart pages are automatically stored incommons:Category:Pages using the Chart extension with rendering errors.Wiki pages with faulty charts are automatically stored inCategory:Pages using the Chart extension with rendering errors in different language versions.
Errors with client side chart rendering will be logged tologstash.(Only for developers.)
There are several conceivable methods to semi-automatically produce and edit the charts and their tabular data:
Edit as table user interface (part of theJsonconfig extension) is available from the .tab edit page. | This extension is being used on one or moreWikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia'sCommonSettings.php andInitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki'sSpecial:Version page. |