Guide

Chartbuilder User Guide

What is Chartbuilder

Chartbuilder is a tool for making charts within our WordPress publishing platform. It was created and is authored by senior engineer Ben Wormald. Its adoption and expansion is guided by associate director Peter Bell. Chartbuilder can be used to create all the Center’s commonly used chart types.

Chartbuilder offers several advantages over publishing static images of charts:

  • Interactivity: It offers interactive hovering, downloadable data, and shareable images of the chart.
  • Accessibility: Text and data are machine readable by search engines and AI. This is very important, because so much of the Center’s work is published as charts. We publish roughly 200 charts per month. The information in Chartbuilder is also accessible to humans using screen readers.
  • Editability: If we need to update chart data, or edit the text, it can be done quickly, by more people.
  • Flexibility: Chartbuilder is continually updated and optimized for our use. We will have custom visualizations that Chartbuilder can’t render interactively. For example, a detailed map created by a designer using GIS software and Adobe Illustrator. In those cases, Chartbuilder can display a high-resolution image as the “guts” and a corresponding data table.

It is important to understand that Chartbuilder is not a data analysis tool like Excel or R. It is a presentation tool. For that reason, software such as Excel and R/pewplots will remain vital pieces of the Center’s toolkit. The Center will continue to use those tools to draft charts for discussion and visual analysis. And, the digital team is exploring Chartbuilder and pewplots interoperability — the ability to "hand-off" a chart from pewplots to Chartbuilder. The pewplots package is a wrapper for ggplot2 that allows users to make Pew-style graphics in R.

Who uses Chartbuilder?

As of October 2025, designers should create and edit charts, format the chart table for presentation, test mobile appearance, and share preview links in Asana. Digital producers should publish the charts, place them in posts, and add any necessary metadata or alt-text. If necessary, writers and editors can make edits to the headers and footers (e.g., title, source and notes) once the chart is placed in a post.

In the future, research teams will also use Chartbuilder. There are two prerequisites:

  • First, Ben and Peter are working on adding dozens of pre-formatted chart settings that mirror the Excel chart template. Like the Excel template, these presets will enable researchers to create a nearly final chart with only a few clicks.
  • Second, WordPress needs text-based track changes and commenting features like those in MS Word. These features are vital to the Center’s editorial workflow but are currently unavailable in WordPress.

Once granular track changes are available in WordPress, it will be practical to train researchers to write and edit both text and charts in WordPress, as they now do in MS Word. At that time, it will also be practical to generate professional-looking pdfs from WordPress, instead of MS Word. (For more information, see the April 2025 Word to WordPress FAQ.)

However, it will be some time before WordPress has track changes like Word does. It is hard to say when; it is not a feature that the Center can engineer by itself. In the meantime, we can use Chartbuilder and the Word/Excel templates in combination.

Chartbuilder and the Editorial Process

As of October 2025, the Center's near-term goal is to begin using Chartbuilder to publish all our charts on pewresearch.org during Q1 2026. Doing so will require some modifications to our production workflows. Primarily, it means that charts will need to be created in both Excel/Word and in Chartbuilder. See preceding paragraphs for why this is necessary.

General Guidelines

These guidelines apply to reports. For Short Reads, see this one page overview.

Authors should provide designers with pre-number checked data for all graphics in the report during the writing and editing phase.

  • Digital and research teams will develop best practices for this handoff, including Asana considerations. It's probably best to do this in one organized handoff, rather than piecemeal. A consistent file-naming structure ("slugs") that is used for both data files and Chartbuilder charts will be important.
  • Providing data for all charts during writing and editing shows the designer how many charts a report contains, and allows them enough time to recreate the charts in Chartbuilder. This timing also ensures the charts are available for placement when digital producers create the report in WordPress.
  • For those graphics researchers don't make themselves using Excel, designers will continue to provide chart "guts" — images that can be placed in the Word report template, as they do now. Designers can create these images using Chartbuilder or if necessary, Adobe Illustrator.
  • Number check changes and copy edits should be made to both the Word/Excel charts and their Chartbuilder versions. See below for details.

The MS Word production document

The Center uses MS Word to draft, edit, number check, and copy edit reports. This results in a production document (.doc) that digital producers use to create HTML posts in our WordPress publishing platform.

This Word document includes charts created using Excel by researchers and those created with designers using Adobe Illustrator. Both Excel and Illustrator charts are placed into pre-formatted MS Word graphic "quick tables" that contain the chart's title, subhead, notes and source line.

In the past, producers created images of these graphics for publication on our website ("snagging"). Chartbuilder replaces the need to snag chart images for our website. However, Chartbuilder does not replace the need to have charts in the production document provided to digital producers. This is for a few reasons:

  • A production document with charts is important for research teams' own record-keeping.
  • A production document with Word/Excel charts shows digital producers where each Chartbuilder graphic should be placed in the web version of the publication.
  • A production document with Word/Excel charts is used to create a publication-ready pdf version of the report that is published on our website alongside the web/HTML version.

Number-checking and copy-editing

The Chartbuilder version of a Word/Excel chart is created independently of the latter. Therefore, if both versions are to be published, number check changes and copy edits must be made to both the Word/Excel chart and the Chartbuilder version.

Alternatively, to avoid duplication of effort, the Chartbuilder version alone can be copy edited and number checked. Then an image of it can be exported for placement in the Word/pdf document.

This is a new step and so digital, research teams and the copy desk will develop best practices for efficiently communicating number check changes and copy edits, and confirming they have been made to Chartbuilder charts. Ben and Peter are adding a feature to Chartbuilder to mark if a chart has been number-checked, and if a chart has been copy-edited. These statuses will help staff know that the Chartbuilder chart is up-to-date.

Creating a chart

Chart creation has three steps: creating the chart block; uploading the csv data to the block; and formatting the chart block.

1. Creating a chart block

To create a new chart, click “Charts” from the WP menu and then click “Add New Chart”. That opens a new chart post.

When the new creation UI is enabled (an administrator turns this on under Charts → Settings), you work through a guided flow on that post: Pattern → Data → Configure → Preview. Pick a type or template, edit data in the embedded power table (or import a CSV), set the most common appearance controls with a live preview, then open the full editor.

Administrators can also open Charts → Settings → Screenshot Settings to choose the screenshot provider and the default capture size, scale, padding, selector, and delay used for featured-image PNGs.

When the classic picker is still the default, you choose a chart type – pie, bar, dot, line, and so forth. After you select a chart type, a dummy chart will appear, pre-populated with data, much like the Center’s Excel chart template.

Now, give the chart a title. Not only is this good practice for creating a chart in which title and plots reinforce each other, it will allow you to identify and return to the chart later.

Create and name a chart

2. Uploading chart data

The dummy chart you just created has two components – a power table, and below it, the chart. These are visible in the main editor, but also in the block menu to the left. If the block menu isn’t visible, click the three horizontal lines in the upper left of the screen to reveal it.

To upload data, select the power table. Once highlighted, a control panel will appear to the right of the editor. Open the “Table data” item and then click, “Import CSV.” Select the .csv file of your chart data and click “open”. The power table will populate and the chart below it will immediately update.

At this point, the chart will be unformatted and ugly. Don’t worry. We’ll format the appearance of this rough chart in the next step.

Upload chart data via CSV

3. Formatting the chart’s appearance

The formatting options in Chartbuilder are extensive. Almost every aspect of the chart’s appearance can be adjusted. Don’t be intimidated by the number of controls. Excel has just as many.

Pre-set templates

In the future, each Chartbuilder block variation will include a list of pre-formatted templates that can be applied to a rough chart with a single click. They will mirror the dozens of options in the Excel template. Once the template is applied, these mostly styled charts can then be refined by designers as needed. For now, formatting a chart requires familiarity with Chartbuilder’s many controls.

Formatting controls and order of operations

To reveal the formatting controls, select the rough chart, either in the editor or in the block listing to its left. A list of expandable menu items will appear at right. Each menu item is expandable and houses a set of related controls.

Chartbuilder's formatting controls, shown in the panel at right.

These controls can be applied in any order. As you format the chart, you will have to adjust some settings a second or third time. This is a normal part of how charts are designed, regardless of tool. However, you can limit the number of re-adjustments by following this basic order of operations:

  1. First, enter the title and subhead using the Text Fields controls. You can also type directly into the chart editor.
  2. Then, set the width and height, using the Chart Layout controls. Pick one of the four standard widths (200px, 310px, 420px, or 640px). Height can be any value.
  3. Adjust the data labels in the chart, using the Labels controls.
  4. For bar and dot plots, adjust the tick length for the labels to the left of the plot using the Independent Axis Configuration controls. Most of the Center's charts are horizontal bar or dot plots, and their y-axis labels often dictate the size of the plot area, the overall width of the chart, or both. So, it makes sense to format the appearance of these labels early. It’s OK if the labels overlap the plot area, you’ll adjust that next.
  5. Adjust the padding-left value of the plot area using the Chart Layout controls. This increases or decreases the whitespace available for the text labels.
  6. Now, add any groupings, annotations, legend, or callouts that you need. Directly labeling chart elements or inserting a chart legend requires space. Usually this is done by increasing the height of the chart, increasing the padding, or both. To add direct labels, use the Text Annotations controls. To add a legend, use the Legend control. Data labels, text annotations and legends are "draggable." That means they can be individually placed using the mouse and cursor.
  7. If the chart is full width, change the width to ~380px to test for appearance on mobile.
  8. Once you’ve created the space for all the elements in the chart, and checked for mobile responsiveness, focus on the appearance of the elements: font size, color, and so forth. See the example charts below to get a sense of what is possible.

Formatting the power table block

Every Chartbuilder chart has the option of showing the data "behind" the plot. This data is shown in a table, in the browser, in the chart frame. Readers access it by clicking the table tab at the bottom of the chart.

Ben and Peter will add some basic default formatting to the power table, to improve appearance. In the meantime, it's a good idea to preview the table view to see if a few formatting changes will improve appearance.

First, right-align any numerical columns and left-align any text columns. This is done by selecting the power table below, and then clicking the down arrow above a table column header. With a column selected, open the "Multi-cells settings" item from the control panel at right, and scroll down to the Cell Alignment controls to set alignment.

Second, if you have 5 or more columns of data, try setting the min-width of the table to 800px. Doing so will make the table scrollable, within the Chartbuilder frame, and the column headers more legible.

It is not necessary to add percentage signs (or other units) to the values in the first row of the table. Our chart subheads usually specify units and measures. Also, machine reading might interpret such differences literally, such that 70% and 70 become 0.7 and 70, respectively.

The data table view of a Chartbuilder chart.

The data table view of a Chartbuilder chart. The power table's min-width has been set to 800px. This is wider than the 420px width of the chart. Doing so enables scrolling. This is done to avoid narrow, crowded columns with hard-to-read column headers.

Mobile design considerations

Most of the Center's charts are designed to be either 310px wide, or 420px wide. As a result, most of our charts are well-suited to phone screens ranging from 360px to 420px. In most such cases, you should leave the "Overflow" control in the Chart Layout panel set to the default "Responsive" option.

Full width, 640px charts won't always display well on a small screen. It's important for the designer to preview the chart's mobile appearance before sharing previews more widely with colleagues. Narrowing the chart's width to ~360px will accomplish this. If the narrowed chart doesn't look very good, the designer has a couple options.

  • If the problem is minor overlap and crowdedness, try adjusting the layout, labels, and spacing of the chart so that it will compress more gracefully.
  • If that is impractical, change the Overflow control to "Scrolling." This works much like a wide power table in the data view described in the previous section, above: the "guts", or plot itself will remain 640px wide. Only the left two-thirds of the chart will appear when the page loads, but users can horizontally scroll the rest of the plot into view.

Mobile Breakpoint Control

More TK on the mobile breakpoint control, what it does, when to use, etc.

Previewing and Placing a Chart

To share a chart with editors in Asana, designers need to enable a public preview. This creates a shareable link you can post in Asana. To do it, click the “chart” tab at the top of the left panel. You can also click outside of the chart in the main editor. The "enable public preview" control is about halfway down the panel – right above “move to trash.” Careful! 🙂

If the chart is published, the public preview control will not appear. Either share the public URL for the chart, or change the chart's publication status to "Draft" and the public preview control will appear.

A chart in Draft status with public preview option enabled.

A chart in "Draft" status with public preview option enabled. The link below the checkbox can be shared in Asana so that editors can view the unpublished chart.

To place a chart, the producer can insert a Chart block and then search for the specific chart to place, by name. The chart block (that is, the block element named “Line”, “Bar,” etc.) should be aligned right.

When a chart is placed in a post, it is editable in place. That is the meaning of “synced” chart: an edit made to any instance of the chart affects every instance of the chart. Thus, if the header or footer of the chart needs to be changed because of edits to the surrounding text, this can be done by an editor working in the post.

Example Charts

Each of the charts below was originally published as a static image on pewresearch.org and then replicated in Chartbuilder. To explore the formatting controls, duplicate one of the charts listed below, rename it, and then edit it.

Was this helpful?